> ## Documentation Index
> Fetch the complete documentation index at: https://docs.temacstore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Solução de Problemas: Erros Comuns nos Scripts FiveM

> Guia de troubleshooting para erros comuns nos scripts FiveM, incluindo problemas de inicialização, banco de dados, UI e integração com frameworks.

Esta página cobre os erros mais comuns ao usar os scripts FiveM e como resolvê-los. Para cada problema, siga os passos em ordem até encontrar a solução. Ative `Config.Debug = true` no `config.lua` para obter mais detalhes nos logs.

## Problemas de Inicialização

<Accordion title="Couldn't start resource: nome-do-script">
  Este erro aparece no console do servidor quando o recurso não pode ser carregado.

  **Causas e soluções:**

  1. **Nome da pasta incorreto** — O nome na linha `ensure` deve ser exatamente igual ao nome da pasta em `resources/`. Verifique maiúsculas/minúsculas.

  2. **fxmanifest.lua ausente** — A pasta do script deve conter o arquivo `fxmanifest.lua` na raiz.

  3. **Dependência não encontrada** — Verifique o `fxmanifest.lua` do script para a lista de `dependencies`. Todos os recursos listados devem estar instalados e iniciados antes deste script.
</Accordion>

<Accordion title="Script inicia mas exibe erros de Lua no console">
  Erros de Lua geralmente indicam um problema de configuração.

  **Passos:**

  1. Leia a mensagem de erro completa — ela indica o arquivo e a linha exata do problema
  2. Verifique se o `config.lua` está com a sintaxe correta (sem vírgulas faltando, aspas abertas, etc.)
  3. Ative `Config.Debug = true` para mais detalhes
  4. Confirme que o framework correto foi detectado

  **Validar sintaxe Lua:**

  ```bash theme={null}
  # Ferramenta online: https://www.lua.org/demo.html
  # Cole o conteúdo do config.lua para verificar erros de sintaxe
  ```
</Accordion>

<Accordion title="Framework não detectado corretamente">
  Se o log mostrar `Framework: nil` ou o script se comportar como se não houvesse framework:

  1. Confirme que o ESX ou QBCore está iniciado **antes** do script no `server.cfg`
  2. Force o framework manualmente: `Config.Framework = 'esx'` ou `Config.Framework = 'qbcore'`
  3. Verifique se o recurso do framework está ativo com `GetResourceState('es_extended')` ou `GetResourceState('qb-core')`
</Accordion>

## Problemas de Banco de Dados

<Accordion title="Database connection error / oxmysql errors">
  1. Verifique se o **oxmysql** está instalado e iniciado antes de todos os outros scripts
  2. Confirme as credenciais do banco de dados no `server.cfg`:
     ```cfg theme={null}
     set mysql_connection_string "mysql://usuario:senha@127.0.0.1/nome_banco?charset=utf8mb4"
     ```
  3. Confirme que o banco de dados existe e o usuário tem permissões
  4. Verifique se o arquivo SQL foi importado corretamente — tabelas ausentes causam erros
</Accordion>

<Accordion title="Tabela não existe (Table doesn't exist)">
  O arquivo SQL do script não foi importado.

  1. Localize o arquivo `.sql` na pasta do script (geralmente `database/nome-script.sql`)
  2. Importe via phpMyAdmin, HeidiSQL ou linha de comando:
     ```bash theme={null}
     mysql -u usuario -p nome_banco < database/meu-script.sql
     ```
  3. Reinicie o script após importar
</Accordion>

## Problemas de Interface (UI)

<Accordion title="HUD sobreposto a outros recursos">
  Se o HUD do script se sobrepõe a outro HUD no servidor:

  1. Ajuste a posição: `Config.UI.HUDPosition = 'bottom-right'`
  2. Adicione offset: `Config.UI.HUDOffset = { x = 20, y = 80 }`
  3. Ou desative o HUD nativo: `Config.UI.ShowHUD = false` se você usa outro sistema de HUD
</Accordion>

<Accordion title="Notificações não aparecem">
  1. Verifique `Config.UI.ShowNotifications = true`
  2. Se usa sistema externo, confirme que o recurso está instalado e o nome correto está em `Config.UI.NotificationSystem`
  3. Verifique o console do cliente (F8) por erros relacionados ao sistema de notificação
</Accordion>

<Accordion title="Menu não abre / NUI não funciona">
  1. Verifique erros no console do cliente (F8)
  2. Confirme que os arquivos HTML/JS do recurso não foram corrompidos
  3. Teste em outro navegador de cliente ou reinstale o recurso
  4. Verifique se algum antivírus bloqueou os arquivos ao descompactar
</Accordion>

## Problemas de Permissões

<Accordion title="Comando não autorizado (You don't have permission)">
  1. Confirme que o identificador do Steam/Discord está correto no `server.cfg`
  2. Verifique a sintaxe do `add_ace` e `add_principal`:
     ```cfg theme={null}
     add_principal identifier.steam:110000112345678 group.admin
     add_ace group.admin meu-script.admin allow
     ```
  3. Reinicie o servidor após alterações no `server.cfg`
  4. Use `test_ace` no console para testar permissões:
     ```
     test_ace identifier.steam:110000112345678 meu-script.admin
     ```
</Accordion>

## Obtendo Suporte

Se o problema persistir após seguir os passos acima:

<CardGroup cols={1}>
  <Card title="FAQ" icon="circle-question" href="/suporte/faq">
    Consulte as perguntas frequentes para respostas rápidas sobre instalação, configuração e uso.
  </Card>
</CardGroup>

<Note>
  Para suporte direto, entre em contato pelo nosso servidor do Discord e abra um ticket. Ao solicitar ajuda, inclua sempre: versão do script, framework utilizado, mensagem de erro completa do console e o conteúdo do seu `config.lua` (remova dados sensíveis como URLs de webhooks antes de compartilhar).
</Note>