O erro Circular plugin loading detected indica que dependências e requisitos de ordem formam um ciclo. Por exemplo, A exige B, B exige C e C exige A. Não há sequência em que cada plugin carregue antes do outro, e Paper encerra startup para evitar escolher uma ordem aleatória.

A correção costuma exigir identificar autores e dependências envolvidas, depois atualizar, substituir ou remover o componente problemático. Ativar o loader legado pode permitir tentativa de compatibilidade, mas Paper avisa que a ordem pode produzir falhas difíceis de depurar e que essa opção pode deixar de ser suportada.

Preserve evidência e configuração

Guarde `latest.log` completo desde o começo da carga, versão de Paper, Java e lista de JARs. Copie o caminho e versão de cada plugin no diretório. Não mova ou renomeie tudo antes de preservar evidência; a ordem e nomes ajudam a reproduzir o ciclo.

Faça backup dos arquivos e de qualquer banco que tenha sido tocado na tentativa. O startup pode inicializar parcialmente plugins antes de parar. Não abra instância concorrente sobre os mesmos mundos e bancos enquanto investiga.

Leia a lista do ciclo no erro

O stack de erro pode mostrar sequência, por exemplo `Plugin1 -> Plugin2 -> Plugin3 -> Plugin1`. Anote todos os participantes e procure requisitos declarados nos metadados e na documentação dos autores. Esse caminho evidencia relação circular; não significa automaticamente que o primeiro plugin é único culpado.

Plugin A pode exigir API de B enquanto B exige integração de A. Dependências `depend`, `softdepend` ou `loadbefore` têm semânticas diferentes, e alguns plugins distribuem bibliotecas externas. Consulte documentação do plugin e confirme nomes técnicos, que podem diferir do nome do JAR.

Confira metadados e versões compatíveis

Depois de registrar o ciclo, compare cada componente com a versão do Minecraft e do Paper. Abra as páginas oficiais ou os repositórios dos autores e procure a versão mínima, dependências obrigatórias, integrações opcionais e alterações recentes. Uma dependência que se tornou obrigatória em uma atualização pode transformar uma combinação que funcionava em um ciclo ou em um requisito impossível.

Em plugins Paper modernos, a declaração de dependências participa do carregamento e define relações que o servidor precisa respeitar. No formato tradicional, depend exige outro plugin; softdepend informa integração opcional e loadbefore sugere uma ordem. Não troque essas chaves aleatoriamente para silenciar o erro: se o código usa classes do outro plugin no startup, declarar a relação como opcional não torna o uso seguro.

Verifique também se há cópias duplicadas do mesmo plugin no diretório. Dois JARs com nomes diferentes podem declarar o mesmo identificador e confundir o diagnóstico. Baixe arquivos apenas da fonte indicada pelo desenvolvedor, confirme a versão e remova versões obsoletas depois de preservar uma cópia da configuração. Não instale versões aleatórias de fóruns para tentar resolver uma cadeia de dependências.

Monte uma reprodução mínima e isolada

Crie uma instância de teste com o mesmo Paper, Java e configuração básica. Copie apenas os plugins participantes e as dependências obrigatórias, mantendo os dados em cópias. Se o ciclo continua com o conjunto mínimo, a evidência aponta diretamente para a combinação de plugins. Se desaparece, reintroduza componentes em grupos pequenos até descobrir a interação adicional.

Não faça esse teste copiando o mundo de produção para uma instância que pode se conectar a serviços reais. Desative integrações externas, como bancos compartilhados, Discord, lojas e sincronização entre servidores. Alguns plugins executam migrações no primeiro carregamento; por isso, um ambiente isolado evita que o teste altere dados usados pelos jogadores.

Guarde o comando de inicialização, a versão exata do servidor e os nomes dos arquivos usados. Um relatório reproduzível reduz idas e vindas com suporte e ajuda a separar falha de dependência de erro de classe, API incompatível ou configuração ausente. A primeira linha útil costuma vir antes do encerramento, então compartilhe o log inteiro, não só o stack trace final.

Corrija a relação na origem

Se um plugin tem atualização compatível que remove o ciclo, teste essa versão isoladamente. Se a integração é opcional, confira se existe configuração oficial para desativá-la sem remover a função principal. Se dois produtos mantêm uma dependência circular estrutural, escolha um deles como dono da integração ou substitua o componente que cria a ligação.

Quando a documentação indicar incompatibilidade entre versões, alinhe toda a família de plugins, incluindo bibliotecas e addons. Atualizar apenas um addon pode introduzir dependência que a versão antiga do plugin principal desconhece. Da mesma forma, fazer downgrade de um plugin que já migrou arquivos pode deixar os dados próprios em formato novo; leia instruções do autor e teste com cópias.

Se a causa estiver nos metadados de um plugin próprio, defina uma direção de dependência clara. O plugin que fornece uma API deve ser carregável antes do consumidor. Relações opcionais devem ser verificadas no código antes do acesso. Dependências de compilação e runtime precisam corresponder ao que o artefato realmente empacota, e plugins que não são necessários no startup não devem declarar uma exigência sem motivo.

Evite tratar o loader legado como solução padrão

Paper oferece a propriedade -Dpaper.useLegacyPluginLoading=true como último recurso de compatibilidade. A documentação alerta que ela pode ser difícil de depurar e não deve ser vista como caminho sustentável. Pode mudar a ordem observada sem corrigir o contrato entre os plugins, e uma futura atualização pode remover o suporte.

Se um teste temporário depender dessa opção, registre-a no relatório e mantenha a instância privada. Confirme funcionalidades críticas em sequência: startup, comandos, permissões, eventos, reinício, desligamento e persistência. Não anuncie o servidor como corrigido só porque chegou ao estado “Done”; o erro pode aparecer depois quando os plugins inicializarem uma integração de forma tardia.

Remova a propriedade assim que houver combinação corrigida e repita o teste em configuração limpa. Ter a opção escondida no painel ou no script de startup meses depois torna o ambiente opaco e dificulta futuras atualizações. O registro da exceção precisa incluir responsável, razão, versão afetada e critério para removê-la.

Valide e documente a correção

Com a correção aplicada, inicie a instância de teste várias vezes, pois algumas integrações só falham após reiniciar ou carregar dados existentes. Verifique os comandos e recursos dos plugins envolvidos, veja se a inicialização está livre de warnings de dependência e confirme que as configurações foram lidas do caminho esperado. Faça backup antes de promover a combinação para produção.

Na janela de manutenção, desligue normalmente, preserve logs e backup, aplique as mesmas versões testadas e abra o servidor à equipe primeiro. Observe o log completo e faça verificações funcionais. Se surgir um erro diferente, pare e analise essa evidência; não empilhe alterações sem saber qual delas mudou o resultado.

Documente o grafo aprovado: plugin principal, dependências, versões, origem dos arquivos e se alguma integração opcional foi desativada. Esse inventário transforma a próxima atualização em uma comparação objetiva e evita reconstruir o diagnóstico do zero. Ao pedir ajuda aos autores, inclua o ciclo, versões exatas, ambiente mínimo e passos para reproduzir, sem anexar dados privados dos jogadores.

Fontes e próximos passos

Use a documentação do Paper para entender o comportamento geral do loader, mas confirme requisitos específicos na página de cada plugin. Os autores podem alterar dependências entre releases, e a configuração de um servidor não substitui os metadados incorporados no JAR. Se o ciclo persistir na combinação mínima, reporte ao mantenedor com evidências; se só ocorre no conjunto completo, procure a integração que fecha o caminho.

Não existe uma ordem universal que resolva qualquer ciclo: se A requer B e B requer A no startup, apenas inverter a lista não cria uma ordem válida. A saída segura é alterar as dependências, trocar versões ou remover uma das ligações, com backup e validação antes da produção.

Desenhe o grafo de dependências

Faça uma lista curta: A depende de B? B carrega antes de C? Algum addon pressupõe que plugin principal esteja disponível durante inicialização? Uma tabela de dependências deixa o ciclo visível. Procure plugins duplicados, forks e versões mistas que possam declarar ordem incompatível.

Confira se biblioteca foi instalada uma única vez e se versões de addon são compatíveis com o plugin principal. Dois plugins podem fornecer o mesmo nome lógico ou integração, e isso confunde resolução. Não use arquivo de desenvolvimento sem motivo só por ter timestamp recente.

Atualize e corrija na raiz

Consulte releases dos autores para ver se o ciclo é conhecido ou foi corrigido. Atualize em cópia e faça um plugin por vez. Se autor orienta remoção de integração opcional ou troca de addon, siga essa instrução. Confirme que função desejada continua ativa depois da mudança.

Se um plugin depende de outro sem oferecer suporte para carregamento moderno, reporte ao autor com stack completo, versão e lista das dependências. O ciclo pode estar no `plugin.yml` ou metadados de loader; apenas usuário que mantém o plugin consegue corrigir sua declaração. Não edite JAR para remover linhas.

Use loader legado somente como último recurso

Paper documenta a propriedade paper.useLegacyPluginLoading como opção para contornar alguns ciclos, mas alerta que pode causar carregamento inesperado e problemas difíceis. Ela não elimina dependência circular; muda o mecanismo que tenta resolver ordem.

Antes de habilitar, confirme com os autores se versão suporta e se há correção. Faça cópia isolada, ligue flag apenas nesse ambiente, confira logs, comandos, eventos e reinícios. Não trate startup bem-sucedido como prova; plugin pode falhar depois em comando, listener ou atualização de dados.

Teste todas as rotas que dependem do grupo

Depois de corrigir, confirme cada plugin na lista de carregados e valide funções entre eles, como economia, permissões, chat ou proteção. Faça um restart completo e teste de novo. Integração pode parecer funcional logo após inicialização, mas quebrar quando reload ou ação agendada ocorre.

Reative componentes gradualmente em homologação e mantenha backup. Se ciclo reaparece, compare a nova sequência e evite reinstalar todos de uma vez. Um teste curto ajuda a encontrar qual atualização alterou grafo.

Saiba quando procurar suporte

Se não há dependência documentada ou ciclo parece vir de interação inesperada, envie evidência aos autores dos plugins envolvidos. Remova segredos, nomes de jogadores e informações que não ajudem. Identifique versão exata e passos para reproduzir numa cópia sem dados privados.

Leia o guia do Paper para diagnosticar circular loading, a referência de dependências declaradas e a explicação do loader moderno e ciclos. Prefira correção da causa a ativar compatibilidade legada sem teste.

Fontes e referências

Documentação consultada em 2026-10-08. Os exemplos precisam ser conferidos na versão instalada; este guia não afirma que a configuração foi testada no seu ambiente.