Pular para o conteúdo
Documentação: Solução de problemas

Documentação · Ajuda

Solução de problemas

Use o doctor, entenda as mensagens mais comuns e peça ajuda com o log certo.

Alfa

Esta documentação corresponde ao OSX-REIMS 0.6.0, em estágio alfa. Comandos e opções podem mudar entre versões; na dúvida, confira osx-reims --help na versão instalada.

Comece pelo doctor

osx-reims doctor

No console, o mesmo está em Maintenance › Check this computer.

O doctor confere o sistema, a GPU, o acesso ao KVM, o Reims vGPU e os arquivos do OSX-REIMS. Ele não muda nada, não pede senha e não usa a internet. Cada verificação aparece como OK, aviso ou falha, com uma dica de como corrigir. No fim, ele mostra o total e o caminho do log.

Para testar também a conexão com o GitHub e com os servidores do Rust, que o setup usa:

osx-reims doctor --online

Resultados comuns do doctor

Verificação O que fazer
Processor: virtualização desligada ou sem suporte Habilite Intel VT-x ou AMD-V no BIOS/UEFI
KVM device: /dev/kvm não existe Habilite a virtualização no BIOS/UEFI e reinicie o computador
Vulkan GPU: nenhuma GPU ou só renderização por software Instale o driver da GPU com suporte a Vulkan
Render node: sem /dev/dri/renderD* Instale o driver da GPU
User groups: grupos salvos, mas ainda não ativos nesta sessão Saia da sessão e entre de novo, ou reinicie o computador
KVM options: salvas, mas ainda não em vigor Reinicie o computador
License: licença não aceita neste computador Rode osx-reims setup e aceite a licença
Local changes: arquivos alterados no Reims vGPU O setup não atualiza o Reims vGPU enquanto houver alterações em /opt/reims-vgpu
Free space: pouco espaço para as VMs Libere espaço: cada VM macOS ocupa dezenas de GB
Nested VMs: não disponível Só em computadores Intel, com a virtualização aninhada ligada no KVM; as VMs iniciam sem o recurso
VM GPU: nenhuma GPU tem VK_EXT_external_memory_host Nenhuma GPU deste computador pode rodar VMs. Em uma NVIDIA, instale o driver completo da NVIDIA; nas demais, atualize o driver Vulkan. Veja Requisitos
VM memory: uma GPU sem VK_EXT_external_memory_host Aviso: aquela GPU não roda VMs; as VMs usam outra
Memory maps: vm.max_map_count abaixo do necessário Rode osx-reims setup
GPU memory access: sem acesso ao /dev/udmabuf (GPUs AMD) Siga a dica: sudo modprobe udmabuf, sair e entrar de novo na sessão ou osx-reims setup
Large GPU buffers: o driver da AMD não aceita buffers grandes Atualize o Mesa para a versão 26 ou mais nova; sem isso, o macOS pode parar na primeira tela acelerada
Build toolchain: falta o Rust, o clang ou outra ferramenta da compilação Rode osx-reims setup: o update-reims e o rebuild-reims precisam dela
VM network: VMs configuradas para a ponte, sem a ponte pronta Rode osx-reims network bridge on, ou coloque essas VMs em NAT
VM GPU, GPU per VM, Sound, Backups Informativas: a GPU em que as VMs rodam neste computador, as VMs com escolha própria, o servidor de som e os backups
Autostart Informativa: qual VM abre sozinha e se o computador faz login automático
Serial number generator ou texto da licença ausente Reinstale o OSX-REIMS
Pacotes, Reims vGPU, QEMU-Reims, programa de inicialização ou pastas Rode osx-reims setup

Quando a dica é Run: osx-reims setup, rodar o setup de novo é seguro: ele só refaz o que falta.

Mensagens comuns

"The environment is not ready"

O console mostra esse aviso no primeiro uso ou depois de uma atualização do OSX-REIMS, com o motivo logo abaixo, como a licença não aceita ou o setup ainda não executado. Pressione S para rodar o setup.

"Virtualization (KVM) is not available in this session yet"

O setup adicionou o seu usuário aos grupos kvm, render e video, mas a mudança só vale em uma nova sessão. Saia da sessão e entre de novo, ou reinicie o computador.

"Virtualization (KVM) is not available on this computer"

A virtualização de hardware está desligada ou não é suportada. Habilite Intel VT-x ou AMD-V no BIOS/UEFI e reinicie.

"The OSX-REIMS license has not been accepted on this computer"

Rode osx-reims setup e aceite a licença. Isso também acontece quando uma nova versão do OSX-REIMS traz um texto de licença novo.

"The VM boot program is outdated"

Costuma aparecer depois de instalar uma nova versão do OSX-REIMS. Rode osx-reims setup. A mensagem "This version of OSX-REIMS does not match the VM boot program" tem a mesma solução.

"Reims vGPU was changed outside setup"

O Reims vGPU em /opt/reims-vgpu não está no commit que o setup compilou. A VM ainda pode iniciar; se falhar, rode osx-reims setup.

"Shut down all VMs first"

O update-reims só roda com todas as VMs desligadas. Desligue-as pelo macOS e tente de novo.

"A VM is being created right now and is using the cache"

O cache não pode ser limpo enquanto uma VM está sendo criada. Espere a criação terminar e tente de novo.

"macOS has not shut down yet"

Pode haver uma confirmação na janela da VM ou um app impedindo o desligamento. Confira a janela da VM e escolha esperar mais, forçar o desligamento ou cancelar.

A janela da VM não abre

Acontecia até a versão 0.3.1 em áreas de trabalho que não usam Wayland: as sessões Cinnamon, MATE e Xfce do Linux Mint e outras sessões X11. A VM rodava sem janela e nada dizia o motivo. Na 0.4.0, o padrão passa a ser o servidor que a sua sessão usa; se preciso, escolha x11 no menu de configurações (C › D) ou inicie com osx-reims start <VM> --x11. Veja Configurações da VM.

"This version of OSX-REIMS needs the new Reims vGPU"

Aparece ao iniciar uma VM logo depois de instalar a 0.6.0 por cima de uma versão anterior: o Reims vGPU no computador ainda é o de antes da reescrita. Com todas as VMs desligadas, rode osx-reims update-reims --tested. Veja O Reims vGPU reescrito.

A VM fecha logo depois de abrir, em uma GPU NVIDIA

O log da inicialização (/opt/osx-reims/logs/latest.log) traz Vulkan failure -3: falta ao driver a biblioteca libcuda.so.1, de que o Vulkan da NVIDIA precisa para o Reims vGPU. Instale o driver completo da NVIDIA (sudo ubuntu-drivers install, ou o pacote nvidia-driver-<versão>), reinicie o computador e inicie a VM de novo. Em uma VM com a GPU automática, o mesmo problema faz a VM rodar em outra GPU.

A GPU não aparece na lista de GPUs, ou "no GPU here has VK_EXT_external_memory_host"

O driver Vulkan da GPU não tem a extensão VK_EXT_external_memory_host, de que o Reims vGPU precisa. É o caso da NVIDIA com o driver aberto nouveau (NVK). Uma GPU assim não é oferecida no menu; quando a escolha automática cairia nela, o start usa a melhor GPU que tem a extensão e diz qual deixou de lado. Sem nenhuma GPU assim, o start recusa. Instale o driver completo da NVIDIA, ou atualize o driver Vulkan da GPU.

A janela da VM fica preta em uma GPU NVIDIA

O macOS roda por trás de uma janela preta quando o Reims vGPU foi compilado sem as correções do OSX-REIMS — o log do setup traz building without it. Acontece ao seguir a versão mais recente ou um commit escolhido. Volte à versão testada com osx-reims update-reims --tested. Veja Versão do Reims vGPU.

O macOS para na tela de boas-vindas, cinza, ou reinicia em laço

Até a 0.4.1, acontecia em computadores cuja única GPU é uma integrada Intel ou AMD, e o OSX-REIMS contornava isso com a configuração memória da GPU. No Reims vGPU reescrito, a memória da VM sempre chega à GPU do mesmo jeito, e a configuração deixou de existir.

Em uma GPU AMD com um Mesa anterior ao 26, a VM pode parar na primeira tela acelerada do macOS (o assistente de configuração, depois da instalação). O doctor avisa nesse caso (Large GPU buffers): atualize o Mesa. O Ubuntu 26.04 já tem um Mesa que funciona.

O teclado não vai para o macOS, ou não volta para o Ubuntu

Clique na janela da VM para o macOS receber o teclado; Ctrl+Alt+Super, pressionadas juntas, devolvem o teclado ao Ubuntu (até a 0.4.1, era Ctrl+Alt+Esc). O título da janela diz em que estado ela está.

O GNOME pergunta sobre atalhos de teclado toda vez

A janela da VM pede ao ambiente os atalhos de que o macOS precisa (Cmd, Alt+Tab, as combinações com Super). No Wayland, o GNOME confirma esse pedido com uma janela toda vez que a VM recebe o teclado, e não guarda a resposta. Iniciar a VM no X11 (C › D, ou --x11) atende ao mesmo pedido sem perguntar.

A VM desligou ao fechar a janela

Fechar a janela da VM a desliga na hora, como tirar da tomada: o que não foi salvo se perde. Desligue o macOS pelo menu Apple, ou com osx-reims stop.

"VM … is set to the bridge, which is not ready"

A VM está configurada para a rede em ponte, e a ponte não existe neste computador. Ligue a ponte em Maintenance › VM network (ou osx-reims network bridge on), ou coloque a VM em NAT em C › N. A VM nunca é movida para o NAT sozinha. A ponte precisa de uma porta de rede com cabo; o Wi-Fi não serve. Veja Rede.

A VM não tem som

Confira se o som da VM está ligado (C › H) e se a linha Audio do resumo não diz que não há servidor de som: sem o PipeWire ou o PulseAudio na sessão, a VM inicia em silêncio. As caixas de som são as escolhidas nas configurações de som do Ubuntu. O som de inicialização do OpenCore só existe nas VMs criadas a partir da 0.6.0.

"The GPU set for this VM … is not on this computer"

A GPU escolhida para a VM não está no computador na hora de iniciar — uma pasta de VM trazida de outro computador, ou uma GPU integrada que a placa-mãe desliga. A VM inicia na GPU automática, a escolha continua salva para quando aquela GPU voltar, e C › U escolhe outra.

A VM com início automático não abriu

O OSX-REIMS não deixa a falha escondida: uma notificação e uma janela de terminal dizem o motivo e abrem o console. Para ver a situação:

osx-reims autostart status

Lembre-se de que só uma VM pode ter o início automático, que ela precisa ter o macOS já instalado e que a VM abre depois do login na sessão — para ligar o computador e chegar ao macOS, o login automático do Ubuntu também precisa estar ligado. Veja Configurações da VM.

As VMs pararam de iniciar depois de uma atualização do sistema

Uma atualização do Ubuntu pode mover bibliotecas sob uma compilação já feita do Reims vGPU. Com todas as VMs desligadas, recompile do zero:

osx-reims rebuild-reims

No console, o mesmo está em Maintenance › Rebuild Reims vGPU. Nada é baixado e a versão não muda; a compilação atual só é removida quando a nova passa nas verificações. Veja Versão do Reims vGPU.

"No osx-reims_*.deb was found in your Downloads or Desktop folder"

O osx-reims update instala o pacote que você já baixou e não baixa nada. Baixe o .deb da versão nova pelo botão Gerar meu link de download no canal #osx-reims do Discord e rode o comando de novo, ou indique o arquivo: osx-reims update <arquivo>.deb. Veja Atualizar e remover.

O pacote não passa na conferência da impressão digital

O arquivo tem a versão publicada, mas a impressão digital (SHA-256) não é a que foi publicada, então ele não é instalado. Baixe o arquivo de novo pelo botão Gerar meu link de download no canal #osx-reims.

A VM não inicia depois de mudar para a versão mais recente do Reims vGPU

Volte para a versão testada:

osx-reims update-reims --tested

"Faulty (incomplete disk)" ou "Faulty (no base disk)"

O disco da VM está incompleto ou falta o disco base. Não apague a VM antes de pedir ajuda: compartilhe o log da última execução dela.

A importação de uma VM falha

As mensagens da importação e o que fazer em cada caso estão em Importar uma VM.

Logs

Cada ação grava um log em /opt/osx-reims/logs/, com a ação, a data e a hora no nome, como osx-reims-start-20260914-213000.log. O mais recente também fica em latest.log, e os 100 mais recentes são mantidos. No console, View logs lista e abre os logs.

Se o seu usuário não puder escrever nessa pasta, o log vai para ~/.local/state/osx-reims/logs/, e a tela avisa.

Para um log mais detalhado, repita a ação com --debug.

Pedir ajuda

Importante

O OSX-REIMS não tem suporte técnico e é fornecido sem garantias. O canal #osx-reims-chat é um espaço de ajuda entre membros: a ajuda é voluntária, e não há garantia de resposta, de prazo ou de solução. Pedidos de suporte por e-mail não são respondidos.

  1. Rode osx-reims doctor e anote o caminho do log mostrado no fim.
  2. Encontre o log da execução com o problema, em View logs ou em /opt/osx-reims/logs/.
  3. Compartilhe os dois logs no canal #osx-reims-chat do Discord dos membros, dizendo o que você fez e o que aconteceu, para que outros membros possam analisar.

Os logs não trazem número de série, MLB, UUID nem ROM das VMs, e o log do doctor não traz nenhum dado de identidade delas. Compartilhar logs nos canais de suporte do Universo Hackintosh é permitido pela licença.

Arquivos instalados intactos

dpkg --verify osx-reims

Se o comando não mostrar nada, os arquivos instalados estão intactos. Se mostrar arquivos alterados, instale o pacote de novo.