Ficheiro de plugin danificado, duplicado ou que não é um plugin: corrigir erros no Minecraft

No Paper e no Spigot, um plugin é um único ficheiro JAR (um arquivo Java) na pasta plugins. Se esse ficheiro estiver danificado, vazio, duplicado ou for, na verdade, uma mod ou uma biblioteca, o servidor não carrega o plugin ou este falha no arranque. Cada secção abaixo trata de uma destas mensagens. Através de "Saber mais" na Saúde do servidor, vais diretamente para a secção certa.

O texto completo encontras na Consola ou em Ficheiros, em logs/latest.log. Normalmente, o mais importante são as linhas imediatamente a seguir à mensagem, pois é aí que está o motivo real. Substitui ficheiros de plugin apenas com o servidor parado. Antes disso, cria uma cópia de segurança em Cópias de segurança, sobretudo se também os ficheiros do mundo ou de configuração puderem ser afetados.

O plugin falha ao ser ativado («Error occurred while enabling»)

Este é o aspeto da mensagem:

Error occurred while enabling <Plugin> v<Version> (Is it up to date?)
java.lang.NoSuchMethodError: '<Method>'
    at <Plugin>-<Version>.jar//<Package>.onEnable(…)

O que está por trás disto: O servidor carregou o plugin, mas este falhou ao ser ativado e desligou-se a si próprio. O servidor continua a funcionar normalmente, mas a função deste plugin falta por completo: sem comandos, sem menus, sem permissões, e no jogo não aparece nenhuma outra mensagem de erro. Se for um plugin de proteção, de permissões ou de início de sessão, essa proteção deixa de existir até corrigires o erro. Na maioria dos casos, o plugin corresponde a uma versão do servidor ou de outro plugin diferente da instalada.

Como resolver:

1. A linha de erro indica o plugin e a versão. Verifica na página do plugin se existe uma versão para a tua versão do servidor e atualiza o plugin.
2. Se por baixo aparecer NoSuchMethodError ou NoClassDefFoundError com o nome de outro plugin, estas duas versões de plugins não são compatíveis entre si. Atualiza um deles para uma versão compatível.
3. Se por baixo aparecer um erro de base de dados como Communications link failure, o plugin não consegue aceder à sua base de dados. Verifica os dados de acesso na configuração do plugin e em Bases de dados.
4. Reinicia o servidor e verifica a Consola.

Bom saber: A mesma mensagem com «disabling» ao parar o servidor é muitas vezes apenas uma consequência do erro de arranque. Mais sobre conflitos de versões: O plugin não é compatível com a versão do servidor.

O ficheiro do plugin é ignorado («Could not load 'plugins/…jar'»)

Este é o aspeto da mensagem:

[ModernPluginLoadingStrategy] Could not load 'plugins/<Plugin>.jar' in 'plugins'
org.bukkit.plugin.UnknownDependencyException: Unknown/missing dependency plugins: [ProtocolLib]. Please download and install these plugins to run '<Plugin>'.

O que está por trás disto: O servidor não conseguiu carregar o JAR indicado como plugin e ignora-o. Um JAR (arquivo Java) é o ficheiro onde está contido um plugin. O resto do servidor pode continuar a funcionar, mas este plugin falta por completo. A causa é um ficheiro danificado ou inválido, ou um JAR sem plugin.yml legível, o ficheiro de descrição pelo qual o servidor reconhece um plugin. Com «Failed to run bootstrapper», um plugin do Paper falhou logo na fase mais inicial do arranque.

Como resolver:

1. Lê a linha por baixo da mensagem. Se aparecer UnknownDependencyException, falta outro plugin: instala o plugin indicado entre parênteses retos.
2. Caso contrário, para o servidor e apaga o JAR em causa em Ficheiros, na pasta plugins.
3. Descarrega uma versão de uma fonte de confiança que corresponda ao teu tipo de servidor (Paper, Spigot) e à tua versão de Minecraft, e carrega-a.
4. Reinicia o servidor.

Bom saber: Se o caminho apontar para plugins/.paper-remapped, trata-se de uma cópia que o Paper cria para plugins do Spigot. Substitui o JAR original em plugins; o Paper volta a gerar a cópia no próximo arranque. Sobre plugins em falta: O plugin precisa de outro plugin.

O plugin falha logo na inicialização («Is it up to date?»)

Este é o aspeto da mensagem:

[<Plugin>] Error initializing plugin '<Plugin>-<Version>.jar' in folder 'plugins' (Is it up to date?)
java.lang.ExceptionInInitializerError

O que está por trás disto: O plugin falhou enquanto o servidor o preparava, ou seja, antes mesmo de ser ativado. Fica desativado, os seus comandos e funções não estão disponíveis e o servidor continua a funcionar sem ele. Quase sempre, a versão do plugin não corresponde à versão do servidor. A linha de erro por baixo indica muitas vezes a versão ou uma classe em falta, isto é, uma parte do programa que o plugin espera encontrar no servidor.

Como resolver:

1. Instala a versão do plugin pensada para a tua versão do servidor, ou atualiza o plugin. A página do plugin indica as versões suportadas.
2. Se ainda não existir uma versão adequada para a tua versão do servidor, aguarda por uma atualização do plugin ou, por agora, mantém-te numa versão suportada em Versão.
3. Se isso não ajudar, remove o plugin para teste e comunica o erro ao autor do plugin, com a mensagem completa.
4. Reinicia o servidor.

Bom saber: Se o Geyser indicar «English locale not found», o ficheiro está incompleto. Descarrega o Geyser novamente a partir da página oficial do projeto. Mais informações: O plugin não é compatível com a versão do servidor.

O Paper não carrega um plugin («Could not load plugin … in folder»)

Este é o aspeto da mensagem:

[ModernPluginLoadingStrategy] Could not load plugin '<Plugin>-<Version>.jar' in folder 'plugins'
org.bukkit.plugin.InvalidPluginException: java.lang.ExceptionInInitializerError

O que está por trás disto: O Paper não conseguiu carregar o plugin indicado durante o arranque. O plugin falta por completo, o resto do servidor arranca. O motivo está na linha imediatamente abaixo, geralmente um plugin.yml danificado, uma dependência em falta ou uma compilação para outra versão do servidor. Uma mensagem sobre «API version string» significa, por exemplo, que a indicação de versão no plugin.yml tem um formato que a tua versão do servidor não compreende.

Como resolver:

1. Lê a linha imediatamente abaixo da mensagem.
2. Descarrega novamente o plugin, adequado à tua versão do servidor.
3. Para o servidor, remove o JAR antigo da pasta plugins em Ficheiros e carrega o novo.
4. Reinicia o servidor e verifica na Consola se o plugin carrega agora.

Bom saber: Se a linha abaixo indicar um plugin em falta, o problema não está no ficheiro em si. Nesse caso, consulta O plugin precisa de outro plugin.

Plugin instalado em duplicado («Ambiguous plugin name»)

Este é o aspeto da mensagem:

[ModernPluginLoadingStrategy] Ambiguous plugin name 'ViaVersion' for files 'plugins/ViaVersion.jar' and 'plugins/ViaVersion-<Version>.jar' in 'plugins'

O que está por trás disto: Dois ficheiros JAR na pasta plugins têm o mesmo nome de plugin. O servidor carrega apenas um deles e não sabes ao certo qual. É habitual acontecer quando se carrega uma nova versão sem apagar a antiga. Ou então dois plugins contêm o mesmo conteúdo, por exemplo o FastAsyncWorldEdit, que já inclui o WorldEdit. O servidor funciona, mas possivelmente com a versão antiga.

Como resolver:

1. A mensagem indica os dois ficheiros. Para o servidor e abre a pasta plugins em Ficheiros.
2. Apaga o JAR duplicado ou mais antigo. Mantém a versão que corresponde à tua versão do servidor.
3. No caso do WorldEdit e do FastAsyncWorldEdit, mantém apenas um dos dois.
4. Reinicia o servidor. O comando plugins na Consola mostra quais os plugins carregados.

Bom saber: Ao atualizar, descarrega ou apaga sempre primeiro o JAR antigo antes de carregares o novo. Com números de versão nos nomes dos ficheiros, é fácil não reparar em plugins duplicados.

Mod em vez de plugin na pasta plugins

Este é o aspeto da mensagem:

[DirectoryProviderSource] Error loading plugin: java.lang.IllegalArgumentException: Directory 'plugins/<Mod>-fabric-<Version>.jar' does not contain a paper-plugin.yml or plugin.yml! Could not determine plugin type, cannot load a plugin from it!

O que está por trás disto: Na pasta plugins existe um JAR sem plugin.yml, ou seja, sem o ficheiro pelo qual o Paper reconhece um plugin. Na maioria das vezes é uma mod para Fabric ou Forge, e o nome do ficheiro contém muitas vezes «fabric» ou «forge». Por vezes é também uma biblioteca Java, como um controlador de base de dados. O Paper não consegue carregar isto e ignora o ficheiro. O servidor continua a funcionar, mas a função pretendida não está disponível.

Como resolver:

1. Apaga o ficheiro indicado da pasta plugins em Ficheiros.
2. Procura na página do projeto uma versão em plugin para Paper ou Spigot. Muitos projetos oferecem ambas.
3. Se só existir uma mod, precisas de um servidor de mods. Em Mudar software / loader, escolhe Fabric, Forge ou NeoForge. Os teus plugins do Paper deixam então de funcionar aí.
4. Reinicia o servidor.

Bom saber: Algumas mods só funcionam no cliente do jogo e não pertencem de todo ao servidor. A mudança de software é descrita em Mudar o software e a versão do servidor no painel.

Ficheiro de plugin substituído com o servidor em execução („zip file closed“)

Este é o aspeto da mensagem:

java.lang.IllegalStateException: zip file closed
java.lang.IllegalStateException: The plugin classloader for <Plugin> has thrown a zip file error.

O que está por trás: Um JAR de plugin foi substituído ou apagado enquanto o servidor estava a funcionar, ou alguém usou /reload. Depois disso, o plugin tenta carregar partes do programa a partir do seu ficheiro, que o servidor já fechou, e gera erros. Isto afeta sobretudo plugins que trabalham constantemente em segundo plano, como o LuckPerms. As funções do plugin podem falhar até o servidor ser reiniciado.

Como resolver:

1. Reinicia o servidor por completo. Normalmente, isso resolve a mensagem.
2. No futuro, substitui os ficheiros de plugins apenas com o servidor parado: parar, substituir o JAR em Ficheiros, iniciar.
3. Evita o /reload. O comando recarrega todos os plugins com o servidor em execução, e muitos plugins não lidam bem com isso.
4. Se a mensagem surgir sem uma troca de ficheiros prévia, lê as linhas anteriores na Consola. Mostram qual é o plugin afetado.

Bom saber: Depois de um reinício limpo, o plugin volta a estar totalmente operacional. Só por causa desta mensagem não se perdem dados, mas as alterações do plugin que não tinham sido guardadas nesse período podem perder-se.

Dois ficheiros de plugin com o mesmo nome („duplicate plugin identifier“)

Este é o aspeto da mensagem:

[ModernPluginLoadingStrategy] Could not load plugin 'worldedit-bukkit-<Versão>.jar' in folder 'plugins'
java.lang.IllegalStateException: Provider SpigotPluginProvider{path=plugins/worldedit-bukkit-<Versão>.jar, …} attempted to add duplicate plugin identifier …

O que está por trás: Dois ficheiros JAR fornecem o mesmo nome de plugin. O Paper carrega apenas um deles e rejeita o outro. Normalmente, a versão antiga e a nova de um plugin estão lado a lado na pasta plugins. Ou então dois plugins reivindicam o mesmo nome: o FastAsyncWorldEdit (abreviado FAWE) já inclui o WorldEdit, pelo que um JAR de WorldEdit adicional entra em conflito. O servidor continua a funcionar, mas o Paper avisa expressamente sobre erros posteriores.

Como resolver:

1. Pára o servidor.
2. Em Ficheiros, na pasta plugins, apaga o JAR mais antigo ou redundante. No caso do FAWE, é o JAR worldedit-bukkit separado.
3. Inicia o servidor e verifica com o comando plugins na Consola que o plugin está carregado apenas uma vez.

Bom saber: Os comandos habituais do WorldEdit continuam a funcionar com o FAWE. Como construir com ele e desfazer erros, mostra-o WorldEdit: selecionar áreas, construir e desfazer.

O ProtocolLib avisa sobre um recarregador de plugins

Este é o aspeto da mensagem:

*** ProtocolLib does not support plugin reloaders! ***
*** Please use the built-in reload command!        ***

O que está por trás: O ProtocolLib intervém profundamente na ligação de rede entre o servidor e os jogadores. Os recarregadores de plugins são plugins como o PlugMan ou o PlugManX, que carregam ou descarregam plugins individuais com o servidor em execução. O ProtocolLib não suporta isso e avisa sobre um estado inconsistente. Nesse caso, o ProtocolLib e todos os plugins que dependem dele podem funcionar mal, por exemplo plugins de anti-cheat ou de apresentação.

Como resolver:

1. Não recarregues o ProtocolLib nem os plugins que o usam com um recarregador de plugins.
2. Depois de alterações em plugins, reinicia o servidor inteiro por completo.
3. Se não precisas do recarregador, remove-o da pasta plugins em Ficheiros, para que não seja usado por engano.
4. Se acabaste de usar um recarregador, faz agora um reinício completo, para que tudo fique carregado de forma limpa.

Bom saber: A mensagem recomenda o comando de recarregamento integrado. Esse também recarrega todos os plugins com o servidor em execução. O caminho mais seguro continua a ser um reinício completo.

Ficheiro na pasta plugins não é um plugin executável

Este é o aspeto da mensagem:

[DirectoryProviderSource] Error preparing plugin context: Directory 'plugins/<Plugin>-<Versão>.jar' failed to update!
Failed to open plugin jar …

O que está por trás: Um ficheiro na pasta plugins não pode ser carregado como plugin e o plugin não arranca. Muitas vezes trata-se do código-fonte em vez do plugin (o nome do ficheiro termina em -sources.jar), da documentação (-javadoc.jar), de uma transferência interrompida, de um ficheiro ZIP renomeado para .jar ou de um plugin para outra plataforma. Também „Invalid plugin.yml“ ou „only DEFLATED entries can have EXT descriptor“ pertencem a este grupo: o ficheiro não está estruturado como um plugin deve estar.

Como resolver:

1. Pára o servidor e apaga o ficheiro indicado de plugins em Ficheiros.
2. Transfere novamente o plugin a partir do site oficial. Usa o .jar propriamente dito, não o -sources.jar nem o -javadoc.jar.
3. Se o plugin vier como arquivo ZIP, extrai-o no teu computador e carrega apenas o JAR que contém.
4. Certifica-te de que o ficheiro é destinado a Paper ou Spigot e reinicia o servidor.

Bom saber: Uma versão para outra plataforma reconhece-se muitas vezes pelo nome do ficheiro ou pela página de transferência, que oferece várias variantes à escolha.

Biblioteca Java está na pasta plugins como se fosse um plugin

Este é o aspeto da mensagem:

[DirectoryProviderSource] Error preparing plugin context: Directory 'plugins/asm-util-<Versão>.jar' failed to update!

O que está por trás: Uma biblioteca Java como o ASM ou o Nashorn está como ficheiro próprio na pasta plugins. As bibliotecas são componentes que os plugins usam internamente, não são plugins. O Paper não consegue carregar este JAR como plugin nem atualizá-lo, e ignora-o. O servidor continua a funcionar. Estes ficheiros vão parar ali, por exemplo, quando um arquivo com vários ficheiros foi carregado por inteiro.

Como resolver:

1. Apaga de plugins o JAR da biblioteca indicada, em Ficheiros.
2. Instala apenas o plugin propriamente dito. Ele traz as suas bibliotecas consigo ou descarrega-as ao arrancar.
3. Reinicia o servidor e verifica a Consola.
4. Se depois um plugin indicar que lhe falta algo, lê as instruções de instalação dele, em vez de colocares bibliotecas à mão.

Bom saber: Se um plugin precisa mesmo de um segundo plugin, indica-o expressamente. Como o reconheces: Plugin precisa de outro plugin.

Ficheiro de plugin está vazio („zip file is empty“)

Este é o aspeto da mensagem:

[DirectoryProviderSource] Error loading plugin: zip file is empty

O que está por trás: Um ficheiro na pasta plugins tem 0 bytes ou o seu carregamento foi interrompido. O Paper não consegue abri-lo e ignora-o. O plugin não está disponível, mas o servidor continua a funcionar. Isto acontece muitas vezes quando a ligação se perde durante o carregamento ou quando a transferência já estava incompleta no teu computador.

Como resolver:

1. Em Ficheiros, abre a pasta plugins e procura o ficheiro com 0 bytes ou com um tamanho invulgarmente pequeno.
2. Apaga-o.
3. Transfere novamente o plugin a partir de uma fonte de confiança e carrega-o com o servidor parado. Espera até o carregamento estar totalmente concluído.
4. Reinicia o servidor e verifica na Consola se o plugin carrega.

Bom saber: Com ficheiros grandes ou numerosos, o SFTP é muitas vezes mais fiável do que o carregamento no navegador, vê Editar ficheiros do servidor no painel e ligar por SFTP.

A tua mensagem não está aqui?

Lê a mensagem completa na Consola ou em logs/latest.log, incluindo as linhas anteriores e posteriores. O nome do ficheiro do plugin encontras na própria mensagem ou no stacktrace, a lista de linhas at indentadas: aí o JAR aparece antes da barra dupla, por exemplo <Plugin>.jar//. Também nomes de pastas como plugins/<Plugin>/ indicam qual é o plugin afetado. Antes de substituíres ficheiros, cria uma cópia de segurança. Se não conseguires avançar, abre um ticket e indica a hora da mensagem.