Servidor txAdmin não inicia: 10 erros comuns e como corrigir

Quando o txAdmin mostra o servidor como “starting” e ele nunca fica verde, a causa é quase sempre uma destas dez: uma chave de licença inválida ou reutilizada, uma porta já em uso, um endereço de bind errado, um banco de dados que recusa a conexão, uma mysql_connection_string digitada errado, recursos iniciados na ordem errada, sv_licenseKey no arquivo errado, artefatos antigos, o login de admin perdido ou permissões de arquivo no Linux. Cada uma imprime uma linha reconhecível no console ao vivo do txAdmin. Encontre essa linha, compare com a lista abaixo, aplique a correção e reinicie.

Abra primeiro o console ao vivo (barra lateral do txAdmin, “Live Console”) e role até a primeira linha vermelha depois do banner de boot. Os erros mais abaixo costumam ser consequência desse primeiro.

1. Chave de licença inválida ou vinculada a outro servidor

O console diz algo como:

[svadhesive] Server license key not found or invalid!

ou, quando a chave já está em uso em outro lugar:

Could not authenticate server license key. Server key is already in use by another server.

Causa. A chave no server.cfg está errada, tem espaços a mais, foi colada com uma quebra de linha ou está sendo usada agora por outro servidor em execução (uma segunda instância do txAdmin, um VPS antigo que você esqueceu de desligar ou um amigo que copiou sua config).

Correção. Abra o Cfx.re Portal, confira a chave e cole de novo em uma única linha:

sv_licenseKey "cfxk_XXXXXXXXXXXXXXXXXXXX_XXXXXX"

Se a chave está em uso em outro lugar, pare o outro servidor ou gere uma chave nova. Chaves são baratas; tempo gasto depurando não é.

2. Porta 30120 ou 40120 já em uso

O console diz:

Could not bind on 0.0.0.0:30120

ou o próprio txAdmin se recusa a abrir com uma mensagem sobre a porta 40120 estar indisponível.

Causa. Outro processo está segurando a porta. Normalmente é um FXServer anterior que não encerrou direito, às vezes um segundo servidor na mesma máquina, ocasionalmente outro jogo ou serviço.

Correção. Encontre e encerre o processo.

Windows:

netstat -ano | findstr :30120
taskkill /PID <pid> /F

Linux:

sudo ss -tulpn | grep 30120
sudo kill <pid>

Se você realmente precisa de dois servidores em uma máquina, mude os endpoints no segundo server.cfg:

endpoint_add_tcp "0.0.0.0:30121"
endpoint_add_udp "0.0.0.0:30121"

e inicie o segundo txAdmin com uma porta diferente, por exemplo +set txAdminPort 40121.

3. Endereço de bind configurado como 127.0.0.1

O console diz nada de alarmante. O servidor inicia, o txAdmin fica verde e ninguém fora da sua máquina consegue conectar. O direct connect dá timeout.

Causa. O server.cfg tem:

endpoint_add_tcp "127.0.0.1:30120"
endpoint_add_udp "127.0.0.1:30120"

que só escuta na interface de loopback. Alguns painéis de hospedagem também injetam isso para evitar exposição pública até você configurar.

Correção. Mude as duas linhas para 0.0.0.0:30120 e garanta que a porta está encaminhada no seu roteador ou liberada no firewall do VPS (ufw allow 30120/tcp e ufw allow 30120/udp no Ubuntu).

4. oxmysql ausente ou conexão com o banco de dados recusada

O console diz:

[oxmysql] Unable to establish a connection to the database (ECONNREFUSED)!

ou:

[oxmysql] Access denied for user 'root'@'localhost' (using password: YES)

Causa. O primeiro significa que o MariaDB ou o MySQL não está rodando, ou está escutando em outro host ou porta. O segundo significa que o usuário ou a senha na sua string de conexão está errado. Se você não vê nenhuma linha [oxmysql] e os recursos do framework reclamam que MySQL é nil, o oxmysql não está no server.cfg ou é iniciado tarde demais.

Correção. Verifique se o serviço do banco de dados está de pé (systemctl status mariadb no Linux, o painel de Serviços no Windows ou o painel de controle do XAMPP). Faça login com as mesmas credenciais por um terminal: mysql -u fivem -p. Se isso falhar, o problema é o usuário, não o FiveM. Depois garanta que ensure oxmysql está perto do topo do server.cfg, antes do framework.

5. mysql_connection_string errada

O console diz:

[oxmysql] Unknown database 'fivem'

ou um erro de conexão que cita um host que você não reconhece.

Causa. A string de conexão tem um erro de digitação no nome do banco de dados, no host ou no formato. Existem dois formatos aceitos, e misturar os dois quebra o parsing.

Correção. Use um destes, adaptado aos seus valores:

set mysql_connection_string "mysql://fivem:password@localhost/fivem?charset=utf8mb4"

set mysql_connection_string "server=localhost;uid=fivem;password=password;database=fivem;charset=utf8mb4"

Se a sua senha contém @, : ou /, use o segundo formato (com ponto e vírgula) ou faça URL-encode dos caracteres no primeiro. E coloque essa linha antes de ensure oxmysql, já que o recurso a lê ao iniciar.

6. Recursos iniciados na ordem errada

O console diz:

SCRIPT ERROR: @qb-garages/server/main.lua:3: attempt to index a nil value (global 'lib')

ou (global 'MySQL'), ou (global 'QBCore'), ou Couldn't find resource ox_lib.

Causa. O script rodou antes de a dependência dele ser carregada. As linhas ensure do server.cfg executam de cima para baixo, e um recurso que declara dependency 'ox_lib' no manifest ainda vai falhar se o ox_lib simplesmente nunca receber ensure.

Correção. Organize o topo do server.cfg assim, e deixe os seus recursos no final:

ensure oxmysql
ensure ox_lib
ensure qb-core        # ou es_extended / qbx_core
ensure ox_inventory   # se usado
# recursos do framework
# seus recursos personalizados por último

Confira também se o fxmanifest.lua do script tem shared_script '@ox_lib/init.lua' quando ele usa lib.; sem essa linha, o mesmo erro de nil aparece mesmo com a ordem correta.

7. sv_licenseKey no arquivo cfg errado

O console diz a mesma mensagem “license key not found” do erro 1, mas você tem certeza de que a chave está correta.

Causa. Deploys do txAdmin têm o server.cfg em txData/<perfil>/, mas muitos tutoriais colocam a chave em um segundo arquivo (config.cfg, permissions.cfg) ou no server.cfg da raiz de uma instalação manual. O txAdmin só lê o arquivo cfg configurado em “Settings > FXServer > CFG File Path”.

Correção. Abra as configurações do txAdmin, anote o caminho exato do cfg e coloque sv_licenseKey nesse arquivo. Remova linhas sv_licenseKey duplicadas em outros lugares; se dois arquivos definem a chave, a última carregada vence, e raramente é a que você editou.

8. Artefatos desatualizados

O console diz coisas como:

This server artifact version is no longer supported

ou recursos falham com natives que “não existem”, ou clientes são kickados com incompatibilidade de versão.

Causa. A build do FXServer é velha demais. O Cfx.re encerra o suporte a artefatos antigos, e o cliente atualiza automaticamente, então um servidor que rodava bem no mês passado pode começar a recusar conexões.

Correção. Baixe a build recomendada mais recente na página de artefatos, pare o servidor, substitua a pasta dos artefatos (alpine/ e run.sh no Linux, a pasta inteira no Windows) e inicie de novo. O txData/ é separado dos artefatos, então sua config e seus recursos sobrevivem. Guarde uma cópia da build antiga até confirmar que a nova funciona; de vez em quando uma build “latest” tem regressão e você vai querer a recomendada anterior.

9. Login de admin master do txAdmin perdido

O console diz nada. O txAdmin abre em localhost:40120 e você não consegue fazer login.

Causa. A senha master foi alterada, o arquivo txData/admins.json foi substituído ou o servidor foi configurado por outra pessoa.

Correção. Pare o servidor por completo e depois inicie o FXServer uma vez com a flag de reset:

FXServer.exe --reset-admin

./run.sh --reset-admin

O txAdmin imprime um PIN novo no console; abra o painel web, digite o PIN e você recupera a conta master. Se essa flag não estiver disponível na sua build, a alternativa é editar o txData/admins.json diretamente: pare o servidor, substitua o hash de senha do seu usuário por um novo hash bcrypt e inicie de novo. Confirme o procedimento exato na documentação do txAdmin da sua versão, porque isso mudou entre releases.

10. Erros de permissão no Linux

O console diz:

bash: ./run.sh: Permission denied

ou o FXServer inicia e depois falha ao escrever em txData com EACCES.

Causa. Os arquivos dos artefatos perderam o bit de execução (comum depois de descompactar com a ferramenta errada ou copiar passando pelo Windows), ou o txData pertence ao root enquanto o servidor roda como outro usuário.

Correção.

chmod +x run.sh alpine/opt/cfx-server/FXServer
sudo chown -R fivem:fivem /home/fivem/server

Rode o servidor como o usuário fivem, não como root. Rodar como root funciona até o dia em que um script escreve onde não deveria.

Como ler o console ao vivo do txAdmin mais rápido

Alguns hábitos que cortam o tempo de depuração pela metade:

• Procure o primeiro erro, não o último. Role até o banner de boot e leia de cima para baixo. A primeira linha vermelha é a causa; as seguintes são consequência.
• Busque por SCRIPT ERROR e Couldn't. Essas duas strings respondem pela maioria das falhas de recurso.
• Anote o nome do recurso entre colchetes. [ script:qb-garages ] diz qual pasta abrir.
• Use refresh e ensure <recurso> pelo console para reiniciar um único recurso em vez do servidor inteiro enquanto testa.
• Confira txData/logs/ quando o console já rolou além do que você precisa. O arquivo de log do servidor guarda tudo.

Nossa skill fivem-basics inclui as strings de erro mais comuns e o que elas significam, o que ajuda se você está colando a saída do console no Cursor ou no Claude Code e quer uma resposta direta.

Como o FiveAI encontra isso para você

Tudo acima é reconhecimento de padrões: ler o console, identificar a linha, aplicar a correção conhecida. É isso que o FiveAI faz na sua máquina. Ele conecta ao txAdmin, lê o console ao vivo e os arquivos de log, testa a conexão com o banco de dados usando a sua mysql_connection_string real e diz qual destes dez (ou algo mais raro) está acontecendo, e então oferece a correção. Você diz “o servidor não inicia desde o último restart” e ele vai lá olhar, em vez de você rolar 800 linhas de saída de boot. Ele também roda localmente, então sua config, suas chaves e seu banco de dados nunca saem do servidor.

Perguntas frequentes

Por que o txAdmin diz que o servidor iniciou, mas ninguém consegue conectar?

O processo do servidor está rodando, mas não está acessível. Confira o erro 3 (endereço de bind 127.0.0.1) e o encaminhamento da porta 30120 TCP e UDP no seu firewall ou roteador. Faça um direct connect em 127.0.0.1:30120 da mesma máquina para confirmar que o servidor em si está bem.

Como redefino a senha do txAdmin?

Pare o servidor e inicie o FXServer uma vez com --reset-admin (veja o erro 9). Ele imprime um PIN que você usa para recuperar a conta master. Se a sua build não suporta a flag, edite o txData/admins.json e substitua o hash de senha.

Preciso reinstalar o txAdmin depois de atualizar os artefatos?

Não. O txAdmin vem dentro dos artefatos e atualiza junto com eles. Seu perfil fica em txData/, que você mantém. Substitua a pasta dos artefatos, inicie o servidor e o txAdmin reconhece o perfil existente.