Unity Abrindo em Safe Mode? Como Sair e Corrigir

O Unity Safe Mode aparece quando o projeto abre com erros de compilação de script: em vez de importar tudo e mostrar um editor quebrado, a Unity oferece um editor reduzido só para você consertar o código. A saída é corrigir a causa, e não fugir do aviso. Aqui você descobre por que o projeto caiu nesse modo e resolve na ordem certa: erro de script, pacote quebrado no Packages/manifest.json, versão de pacote incompatível depois de um upgrade e, só no fim, a pasta Library.

Tudo aqui segue a documentação do Unity 6.3 LTS, conferida em outubro de 2026.

O que é o Safe Mode da Unity

Quando você abre um projeto com erro de compilação, a Unity mostra o diálogo Enter Safe Mode? com três botões:

• Enter Safe Mode: a opção recomendada. Abre o editor reduzido para corrigir os erros.
• Ignore: abre o projeto no estado quebrado.
• Quit: fecha a Unity. A documentação sugere essa opção para quem não é responsável pelos scripts que falharam (por exemplo, o artista do time que puxou um commit quebrado e vai esperar o programador corrigir).

Dentro do Safe Mode, ficam disponíveis só quatro janelas: Console, Project, Inspector e Package Manager. No Project, só arquivos ligados a script podem ser selecionados (.cs, .dll, .asmdef, .rsp, .ruleset); o resto aparece acinzentado. Não dá para abrir ou criar cena, os menus GameObject e Component somem e a importação de assets fica limitada ao que é script.

Parece restritivo, e é de propósito. Importar texturas, modelos e áudio de um projeto grande leva tempo, e fazer isso com código quebrado gera uma cascata de erros secundários (componentes como script faltando, importadores customizados que não rodam). O Safe Mode pula tudo isso.

A Unity sai do Safe Mode sozinha assim que os erros de compilação são resolvidos, e aí importa o projeto normalmente.

Por que o projeto abriu em Safe Mode

A documentação lista as causas comuns, e na prática elas se resumem a quatro situações:

1. Erro nos seus scripts. Você fechou a Unity com código pela metade, ou editou um script fora dela.
2. Pacote faltando ou errado. O manifest.json aponta para um pacote que não existe, uma versão que não baixa, ou um caminho local que sumiu.
3. Upgrade de versão da Unity. O projeto foi aberto numa versão diferente da que foi criado, e um pacote ou API não é compatível.
4. git pull com código quebrado. Alguém do time subiu um script que não compila, ou subiu código que depende de um pacote que não foi junto.

Em outubro de 2026 o caso 3 está em alta: o Unity 6.0 LTS sai de suporte este mês, e muita gente está migrando projetos para o Unity 6.3 LTS, a versão LTS atual. Se o Safe Mode apareceu logo depois de você trocar a versão no Unity Hub, comece pela seção de versão, mais abaixo.

Corrigindo erros de script dentro do Safe Mode

Abra o Console (ele já vem aberto no Safe Mode) e leia o primeiro erro. O formato é Assets/Scripts/Arquivo.cs(linha,coluna): error CSxxxx: descrição. Dois cliques abrem o arquivo na IDE, que funciona normalmente no Safe Mode.

O roteiro:

1. Corrija o primeiro erro, salve e volte para a Unity. Ela recompila.
2. Se os erros acabaram, a Unity sai do Safe Mode e importa o projeto.
3. Se sobrou erro, repita.

Os erros mais comuns têm guia próprio: tipo ou namespace não encontrado (CS0246), ponto e vírgula, chave sem par, API renomeada. O post sobre Unity que não entra no Play Mode por erros de compilação cobre os seis mais frequentes e como isolar um asset de terceiros que quebrou o projeto. A técnica de isolar vale igual no Safe Mode: feche a Unity, renomeie a pasta do asset suspeito com um ~ no fim (AssetSuspeito~), e a Unity passa a ignorar essa pasta na próxima abertura.

Se o erro é num script que você não precisa agora e não sabe corrigir, comentar o arquivo inteiro com /* */ também tira o projeto do Safe Mode. Anote o que comentou para não esquecer.

Pacote quebrado: Packages/manifest.json

Quando o erro fala de pacote (Packages/... no caminho, ou uma mensagem do Package Manager de que não conseguiu resolver dependências), o arquivo culpado é o Packages/manifest.json. Ele lista os pacotes do projeto no bloco "dependencies", cada um com nome e versão, URL de Git ou caminho local.

Os defeitos comuns:

• Caminho local que não existe mais: "com.minhaempresa.ferramentas": "file:../Ferramentas", e a pasta foi movida.
• URL de Git inacessível ou com tag apagada.
• Versão que não existe para a sua Unity, digitada à mão ou vinda de outro projeto.
• JSON inválido: vírgula sobrando depois do último item, aspas faltando.

O conserto:

1. Primeiro tente pelo Package Manager, que funciona dentro do Safe Mode: remova o pacote problemático ou troque a versão pela recomendada.
2. Se o Package Manager nem lista o pacote, feche a Unity, abra o manifest.json num editor de texto, faça backup e remova a linha do pacote quebrado. Confira se o JSON continua válido (sem vírgula depois do último item).
3. Se existir Packages/packages-lock.json, você pode apagá-lo; a Unity recria com as versões resolvidas.
4. Abra o projeto e reinstale o pacote pelo Package Manager, na versão compatível.

Esse arquivo é de texto e precisa estar no controle de versão. Com Git, qualquer mudança no manifest aparece no diff, e um git checkout -- Packages/manifest.json desfaz uma edição errada. O post sobre controle de versão para jogos com Git LFS mostra quais pastas do projeto Unity entram no repositório.

Projeto que quebra a cada upgrade, pacote ou git pull é o tipo de atrito que faz muita gente desistir de um jogo que estava indo bem. No curso de Unity você monta um projeto completo do zero ao build com Git, pacotes e organização desde o primeiro dia, para que abrir o projeto no dia seguinte não seja surpresa.

Projeto aberto em outra versão da Unity

A versão com que o projeto foi salvo fica em ProjectSettings/ProjectVersion.txt. Se você abre esse projeto numa versão mais nova, a Unity avisa e faz o upgrade dos assets. O upgrade é de mão única: depois de aberto no Unity 6.3, o projeto não volta limpo para o 6.0.

O que costuma quebrar no upgrade:

• APIs renomeadas ou removidas. A Unity tem o API Updater, que mostra um diálogo pedindo permissão para atualizar automaticamente chamadas obsoletas nos seus scripts. Aceite, depois de ter feito commit, e revise o diff.
• Pacotes presos a versões antigas. O manifest.json guarda a versão do pacote que o projeto tinha. Na versão nova da Unity, um pacote antigo pode não compilar. Abra o Package Manager e atualize os pacotes para as versões marcadas como recomendadas para o seu editor.
• Assets da Asset Store sem suporte à versão nova. Confira a página do asset e atualize pela seção My Assets do Package Manager.

A forma segura de fazer upgrade:

1. Commit de tudo (ou cópia da pasta inteira do projeto).
2. No Unity Hub, troque a versão do editor do projeto.
3. Abra, aceite o API Updater, corrija os erros no Safe Mode se ele aparecer.
4. Atualize pacotes pelo Package Manager.
5. Teste uma build antes de seguir trabalhando.

Se você está saindo do 6.0 LTS, mire no 6.3 LTS e não pule direto para a versão Supported Update mais recente, a não ser que precise de algo dela. O post sobre as novidades do Unity 6.6 ajuda a decidir se vale.

Apagar a pasta Library: quando e como

A Library é cache de importação. A Unity recria tudo a partir de Assets, Packages e ProjectSettings. Apagar ela resolve problema de cache corrompido, e não resolve erro de código.

Quando faz sentido:

• O Console aponta para um arquivo que você já apagou ou corrigiu, e o erro não some.
• O erro aparece dentro de Library/PackageCache depois de você já ter trocado a versão do pacote.
• A importação trava sempre no mesmo ponto.

Como fazer com segurança:

1. Feche a Unity.
2. Faça commit ou copie o projeto.
3. Apague só a pasta Library. Nunca Assets, Packages ou ProjectSettings. A pasta Temp também pode ir.
4. Abra o projeto e espere a reimportação, que em projeto grande pode demorar bastante.

Ignorar o Safe Mode: quando NÃO fazer

O botão Ignore abre o projeto com os scripts quebrados. Os componentes com erro aparecem como script faltando, nada roda no Play Mode e qualquer cena salva nesse estado pode perder referências de componentes. Não use Ignore para "trabalhar um pouco enquanto isso": você corre o risco de salvar cenas e prefabs com referências perdidas.

Também existe a opção Show Enter Safe Mode Dialog em Edit > Preferences > Asset Pipeline. Desmarcada, a Unity entra no Safe Mode direto, sem perguntar, o que é prático para quem já sabe o que fazer. Em modo de linha de comando (batch mode), a Unity encerra quando há erro de compilação, a não ser que você passe o argumento -ignoreCompilerErrors.

O botão Exit Safe Mode na barra de ferramentas sai antes de corrigir. A documentação não recomenda, e a Unity pede confirmação. Só use se você precisa olhar algo que o Safe Mode esconde e vai voltar a corrigir em seguida.

Próximo passo

Da próxima vez que o diálogo aparecer, entre no Safe Mode e siga a ordem: Console e scripts, depois manifest.json, depois versão, e a Library só no fim. Para não chegar nesse ponto, faça commit antes de qualquer upgrade de Unity ou de pacote. E se você ainda está decidindo para qual versão migrar, comece pela LTS atual, a 6.3, que tem suporte até dezembro de 2027.