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

# Erros e Soluções

> Guia de solução de problemas comuns do dk_races

# 🔧 Erros e Soluções

Encontrou um problema? Esta página contém as soluções para os erros mais comuns do **dk\_races**.

***

## 🔐 Problemas de Autenticação

<AccordionGroup>
  <Accordion title="Erro: Script não autenticado" icon="lock" defaultOpen>
    ### Problema

    O console exibe mensagem de que o script não foi autenticado, ou aparece erro no F8.

    ### Causas Possíveis

    * IP do servidor não cadastrado na licença
    * Licença expirada ou inválida
    * Problemas de conexão com o servidor de autenticação

    ### Soluções

    <Steps>
      <Step title="Verifique o IP">
        Confirme se o IP atual do seu servidor está cadastrado na licença.
      </Step>

      <Step title="Altere o IP">
        Acesse a sala **💻・comandos** no Discord e use o comando para alterar o IP.
      </Step>

      <Step title="Reinicie o servidor">
        Após alterar o IP, reinicie completamente o servidor FiveM.
      </Step>

      <Step title="Abra um ticket">
        Se o problema persistir, abra um ticket no Discord com os logs do console.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

***

## 🎮 Problemas de Gameplay

<AccordionGroup>
  <Accordion title="Erro: Você precisa estar em um veículo" icon="car">
    ### Problema

    Mensagem aparece ao tentar acessar o painel da corrida.

    ### Solução

    * Entre em um veículo antes de se aproximar do ponto de corrida
    * Certifique-se de estar no **banco do motorista**
    * Veículos de passageiro não são aceitos
  </Accordion>

  <Accordion title="Erro: Veículo não permitido nesta corrida" icon="ban">
    ### Problema

    O veículo atual não é aceito na corrida selecionada.

    ### Solução

    Verifique quais classes de veículos são permitidas na corrida:

    | Classe        | Tipos de Veículos                                      |
    | ------------- | ------------------------------------------------------ |
    | `cars`        | Compactos, Sedans, SUVs, Coupes, Muscle, Sports, Super |
    | `trucks`      | Caminhões, Utilitários                                 |
    | `motorcycles` | Motos, Quadriciclos                                    |
    | `bicycles`    | Bicicletas                                             |
    | `boats`       | Barcos                                                 |
    | `helicopters` | Helicópteros                                           |
    | `planes`      | Aviões                                                 |

    <Tip>
      O administrador pode configurar as classes permitidas ao criar a corrida.
    </Tip>
  </Accordion>

  <Accordion title="Erro: Você não possui o item necessário" icon="box">
    ### Problema

    A corrida exige um item específico para participar.

    ### Solução

    * Verifique qual item é necessário no painel da corrida
    * Obtenha o item através do sistema do seu servidor
    * Certifique-se de ter a **quantidade necessária**

    <Info>
      Itens comuns: `credential`, `raceticket`, `ticket`
    </Info>
  </Accordion>

  <Accordion title="Erro: A fila da corrida está cheia" icon="users">
    ### Problema

    Não há mais vagas na fila de espera da corrida.

    ### Solução

    * Aguarde a corrida atual terminar
    * Tente novamente quando houver vagas
    * O administrador pode aumentar o limite de pontos na fila
  </Accordion>

  <Accordion title="Erro: Já existe uma corrida em andamento" icon="circle-play">
    ### Problema

    O servidor está configurado para permitir apenas uma corrida por vez.

    ### Solução

    * Aguarde a corrida atual terminar
    * Esta é uma configuração do servidor (`Config.singleRace = true`)
  </Accordion>

  <Accordion title="Erro: Corrida cancelada por falta de corredores" icon="user-slash">
    ### Problema

    Não havia corredores suficientes quando a corrida deveria iniciar.

    ### Solução

    * Certifique-se de ter o mínimo de corredores exigido
    * Verifique a configuração `min_runners` da corrida
    * Convide mais jogadores para participar
  </Accordion>
</AccordionGroup>

***

## 🛠️ Problemas de Configuração

<AccordionGroup>
  <Accordion title="Blips não aparecem no mapa" icon="map">
    ### Problema

    Os blips das corridas não estão visíveis no mapa do jogo.

    ### Soluções

    1. Verifique se a corrida está **ativada** (`active = true`)
    2. Confirme que o `startBlip` foi configurado corretamente
    3. Reinicie o script:

    ```
    refresh
    start dk_races
    ```

    4. Verifique se há erros no console F8
  </Accordion>

  <Accordion title="Checkpoints não aparecem" icon="location-dot">
    ### Problema

    Durante a corrida, os checkpoints não são exibidos.

    ### Soluções

    1. Verifique a configuração em `Config.checkpointsParams`
    2. Confirme que a rota tem checkpoints definidos
    3. Verifique se o `checkpoint.model` é um modelo válido
    4. Consulte os modelos em: [FiveM Checkpoints](https://docs.fivem.net/docs/game-references/checkpoints/)
  </Accordion>

  <Accordion title="Sons não tocam" icon="volume-xmark">
    ### Problema

    Os sons de checkpoint, vitória ou contagem regressiva não funcionam.

    ### Soluções

    1. Verifique se os sons estão habilitados em `Config.Sounds`
    2. Confirme que `enabled = true` para cada som
    3. Verifique se os nomes dos sons são válidos
    4. Consulte: [Sons do GTA V](https://pastebin.com/A8Ny8AHZ)
  </Accordion>

  <Accordion title="Webhooks não enviam mensagens" icon="discord">
    ### Problema

    As notificações não chegam no Discord.

    ### Soluções

    1. Verifique se a URL do webhook está correta em `Config.Webhooks`
    2. Confirme que o webhook está ativo no Discord
    3. Teste a URL manualmente com uma ferramenta como Postman
    4. Verifique permissões do canal do webhook
  </Accordion>

  <Accordion title="Itens coletáveis não funcionam" icon="gem">
    ### Problema

    Os power-ups não aparecem ou não funcionam durante a corrida.

    ### Soluções

    1. Verifique se `Config.CollectableItems.enabled = true`
    2. Confirme que a corrida tem `collectable_items = true`
    3. Verifique a `chanceToHaveItem` (0-100)
    4. Certifique-se de que há itens na lista com `enabled = true`
  </Accordion>
</AccordionGroup>

***

## 🔧 Problemas Técnicos

<AccordionGroup>
  <Accordion title="Erro no console: attempt to index nil" icon="code">
    ### Problema

    Erro Lua indicando tentativa de acessar valor nulo.

    ### Causas Comuns

    * Configuração incompleta ou inválida
    * Arquivo de configuração corrompido
    * Dependência não carregada

    ### Soluções

    1. Verifique se `dk_snippets` está iniciado **antes** do `dk_races`
    2. Revise os arquivos de configuração por erros de sintaxe
    3. Restaure o arquivo original e reconfigure
  </Accordion>

  <Accordion title="Erro: Framework não detectado" icon="plug">
    ### Problema

    O script não consegue identificar o framework do servidor.

    ### Solução

    O script é **STANDALONE** e funciona sem framework. Porém, para recompensas funcionarem:

    1. Verifique a integração em `server/functions/framework.lua`
    2. Implemente as funções necessárias para seu framework
    3. Configure `Config.dirtyDollarItem` para frameworks VRP
  </Accordion>

  <Accordion title="Lag/FPS baixo durante corridas" icon="gauge-simple">
    ### Problema

    Quedas de performance durante as corridas.

    ### Soluções

    1. Reduza a quantidade de partículas:
       * Em `Config.checkpointsParams`, defina `particles = nil`
    2. Desative props nos checkpoints:
       * Defina `prop.enabled = false`
    3. Reduza a escala dos checkpoints
    4. Limite o número de jogadores por corrida
  </Accordion>

  <Accordion title="Banco de dados não salva" icon="database">
    ### Problema

    Rankings, estatísticas ou corridas não são salvos.

    ### Soluções

    1. Verifique o caminho em `Config.noSqlPath`
    2. Confirme permissões de escrita na pasta
    3. Verifique se a pasta existe no servidor
    4. Reinicie o servidor para forçar salvamento
  </Accordion>
</AccordionGroup>

***

## 📝 Erros de Permissão

<AccordionGroup>
  <Accordion title="Erro: Você não tem permissão para isso" icon="shield-halved">
    ### Problema

    Ação bloqueada por falta de permissão.

    ### Soluções

    1. Verifique sua permissão no framework (ADMIN/USER)
    2. Revise `Config.Permissions` no arquivo de configuração:

    ```lua theme={null}
    Config.Permissions = {
        ["race_management"] = "ADMIN",  -- Apenas admins
        ["routes_creation"] = "USER",   -- Todos podem criar rotas
        -- ...
    }
    ```

    3. Para dar acesso a todos, mude de `"ADMIN"` para `"USER"`
  </Accordion>
</AccordionGroup>

***

## 🆘 Ainda Precisa de Ajuda?

Se você não encontrou a solução para seu problema:

<Steps>
  <Step title="Colete informações">
    * Prints do erro no console (F8)
    * Logs do servidor
    * Configurações alteradas
  </Step>

  <Step title="Abra um ticket">
    Acesse nosso Discord e abra um ticket no canal de suporte.
  </Step>

  <Step title="Descreva o problema">
    Explique detalhadamente o que acontece, quando acontece e os passos para reproduzir.
  </Step>
</Steps>

<Card title="Abrir Ticket de Suporte" icon="headset" href="https://discord.gg/NJjUn8Ad3P" horizontal>
  Nossa equipe está pronta para ajudar você a resolver qualquer problema!
</Card>