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.

„Error occurred while enabling …“: o plugin não arranca

O que a mensagem mostra:

Error occurred while enabling EssentialsSpawn v<Version> (Is it up to date?)
Error occurred while enabling WorldEditDisplay v<Version> (Is it up to date?)
Error occurred while disabling FurnitureLib v<Version>

O que está por trás disto: O servidor carregou o plugin, mas este falhou ao ser ativado e foi desligado. O servidor continua a funcionar, mas as funções desse plugin deixam de estar disponíveis por completo. Se for um plugin de proteção, de permissões ou de login, essa proteção também deixa de existir. Na maioria dos casos, o plugin não é compatível com outra versão do servidor ou de outro plugin instalado.

Como resolver:

  1. A linha de erro indica o plugin e a versão. Verifica na página do plugin qual a versão que suporta a versão do teu servidor e atualiza com o servidor parado.
  2. Se por baixo aparecer NoSuchMethodError (falta um método) ou NoClassDefFoundError (falta um componente do programa), verifica as dependências indicadas. Por exemplo, o EssentialsSpawn e o EssentialsX têm de ser compatíveis entre si; uma referência a Bukkit pode dizer respeito à interface do servidor.
  3. Em caso de erro de base de dados, como Communications link failure, verifica os dados de acesso na configuração do plugin e em Bases de dados.
  4. Reinicia e verifica na Consola se o plugin é ativado com sucesso.

Bom saber: „Error occurred while disabling“ diz respeito ao desligamento. Se aparecer depois de um erro de ativação, verifica primeiro esse erro anterior. Mais informaçõ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.

„Error initializing plugin …“: o plugin falha ao iniciar

Este é o aspeto da mensagem:

[<Plugin>] Error initializing plugin '<Plugin>-<Version>.jar' in folder '<Folder>' (Is it up to date?)
java.lang.ExceptionInInitializerError
java.lang.ArrayIndexOutOfBoundsException: Index <Index> out of bounds for length <Length>

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 funcionalidades não estão disponíveis e o servidor continua a funcionar sem ele. Na maioria dos casos, a versão do plugin não é compatível com a versão do servidor. A linha de erro abaixo indica muitas vezes a versão ou uma classe em falta, ou seja, uma parte do programa que o plugin espera encontrar no servidor.

Como resolver:

  1. Lê primeiro as linhas seguintes em logs/latest.log, em Ficheiros, especialmente Caused by. Elas indicam a causa real.
  2. Instala a versão do plugin adequada à tua versão do servidor ou atualiza o plugin. A página do plugin indica as versões suportadas.
  3. 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 em Versão uma versão suportada.
  4. Se isso não ajudar, remove o plugin como teste e comunica o erro ao autor do plugin, com a mensagem completa.
  5. Reinicia o servidor.

Bom saber: Se o Geyser indicar „English locale not found“, o ficheiro está incompleto. Transfere 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.

„Ambiguous plugin name …“: o plugin está instalado em duplicado

O que a mensagem mostra:

[ModernPluginLoadingStrategy] Ambiguous plugin name 'ViaVersion' for files 'plugins/ViaVersion.jar' and 'plugins/ViaVersion-<Version>.jar' in 'plugins'
[ModernPluginLoadingStrategy] Ambiguous plugin name 'LPC' for files 'plugins/.paper-remapped/LPC-<Version>.jar' and 'plugins/.paper-remapped/LPC-<OtherVersion>.jar' in 'plugins/.paper-remapped'
[ModernPluginLoadingStrategy] Ambiguous plugin name 'Slimefun' for files 'plugins/.paper-remapped/<File>.jar' and 'plugins/.paper-remapped/<OtherFile>.jar' in 'plugins/.paper-remapped'

O que está por trás disto: Dois ficheiros JAR indicam o mesmo nome interno de plugin, mesmo que os nomes dos ficheiros sejam diferentes. É típico haver uma versão antiga e uma nova, ou duas variantes do mesmo plugin. O servidor carrega apenas um deles e pode acabar por funcionar com a versão indesejada.

Como resolver:

  1. Para o servidor e abre a pasta plugins em Ficheiros.
  2. Associa os dois ficheiros indicados aos respetivos JAR originais. A pasta plugins/.paper-remapped contém cópias adaptadas pelo Paper; remove o JAR original indesejado em plugins, e não apenas a respetiva cópia.
  3. Mantém exatamente uma versão, que seja compatível com a versão do teu servidor. Não apagues as pastas de dados dos plugins.
  4. Reinicia. Verifica a Consola quanto à mensagem; o comando plugins mostra os plugins carregados.

Bom saber: Atualiza os plugins com o servidor parado e remove o JAR antigo antes de carregares o novo.

„does not contain a paper-plugin.yml or plugin.yml“: o ficheiro não é um plugin

Este é o aspeto da mensagem:

Directory 'plugins/<Mod>-fabric-<Version>.jar' does not contain a paper-plugin.yml or plugin.yml!
Directory 'plugins/<Mod>-neoforge-<Version>.jar' does not contain a paper-plugin.yml or plugin.yml!

O que está por trás disto: Na pasta plugins existe um JAR sem plugin.yml e sem paper-plugin.yml, ou seja, sem um dos ficheiros de descrição de plugins. Na maioria dos casos, trata-se de um mod para Fabric, Forge ou NeoForge; por vezes é uma biblioteca Java, como um controlador de base de dados. O Paper e as suas variantes não conseguem carregar este ficheiro como plugin e ignoram-no. O servidor continua a funcionar, mas a funcionalidade pretendida não está disponível.

Como resolver:

  1. Para o servidor e remove o ficheiro indicado de plugins/, em Ficheiros.
  2. Procura na página do projeto uma versão para Paper ou Spigot, adequada à tua versão do Minecraft.
  3. Se só existir um mod, verifica primeiro se ele deve mesmo ser instalado no servidor. Alguns mods funcionam exclusivamente no cliente do jogo.
  4. Se quiseres mudar para um servidor com mods, cria antes uma cópia de segurança em Cópias de segurança. Em Mudar software / loader, seleciona exatamente o loader exigido pelo mod. Os teus plugins Paper deixam de funcionar aí.
  5. Reinicia e verifica a Consola.

A mudança de software é descrita em Mudar o software e a versão do servidor no painel.

"zip file closed": ficheiro do plugin substituído com o servidor em funcionamento

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.
io.netty.handler.codec.EncoderException: java.lang.BootstrapMethodError: java.lang.IllegalStateException: zip file closed

O que está por trás: Um JAR de plugin, ou seja, o ficheiro de programa de um 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 já fechado e gera erros. As funcionalidades do plugin podem falhar até o servidor reiniciar. A mensagem também pode aparecer ao parar o servidor.

Como resolver:

  1. Reinicia o servidor por completo. Se o JAR do plugin afetado estiver em falta, restaura-o antes, com o servidor parado, em Ficheiros.
  2. No futuro, troca ficheiros de plugins apenas com o servidor parado: pára o servidor, substitui o JAR em Ficheiros e inicia-o.
  3. Evita o /reload. O comando recarrega os plugins com o servidor em funcionamento e muitos plugins não lidam bem com isso.
  4. Se a mensagem aparecer sem uma troca de ficheiros prévia, lê as linhas anteriores na Consola. Elas ajudam-te a encontrar o plugin afetado.

Bom saber: as alterações que o plugin ainda não tenha guardado durante o erro podem perder-se.

"duplicate plugin identifier": dois ficheiros de plugin reivindicam o mesmo nome

Este é o aspeto da mensagem:

[ModernPluginLoadingStrategy] Could not load plugin '<Plugin>.jar' in folder 'plugins'
[ModernPluginLoadingStrategy] Could not load plugin '<Plugin>.jar' in folder 'plugins/.paper-remapped'
java.lang.IllegalStateException: … attempted to add duplicate plugin identifier <Plugin> …

O que está por trás disto: Dois ficheiros JAR disponibilizam o mesmo nome de plugin; o Paper carrega apenas um deles e rejeita o outro. Na maioria dos casos, 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 adicional do WorldEdit entra em conflito. O servidor continua a funcionar, mas o Paper avisa expressamente sobre erros subsequentes.

Como resolver:

  1. Pára o servidor.
  2. Em Ficheiros, na pasta plugins, apaga o JAR mais antigo ou redundante. No caso do FAWE, trata-se do JAR separado worldedit-bukkit.
  3. Se a mensagem mencionar plugins/.paper-remapped, verifica primeiro os ficheiros JAR originais na pasta plugins à procura de versões duplicadas.
  4. Inicia o servidor e verifica na Consola se o aviso desapareceu e se o plugin pretendido é carregado.

Bom saber: Os comandos habituais do WorldEdit continuam a funcionar com o FAWE. Como construir com ele e anular erros, mostra-to WorldEdit: selecionar áreas, construir e anular alterações.

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.

"Error loading plugin": ficheiro de plugin ou nome de plugin inválido

Este é o aspeto da mensagem:

[DirectoryProviderSource] Error preparing plugin context: Directory 'plugins/<Ficheiro>.jar' failed to update!
[DirectoryProviderSource] Error loading plugin: Directory 'plugins/<Ficheiro>.jar' failed to load!
[DirectoryProviderSource] Error loading plugin: Restricted name, cannot use 0x20 (space character) in a plugin name.

O que está por trás disto: Não é possível carregar um ficheiro na pasta plugins; o plugin não arranca. Com frequência, encontra-se aí o código-fonte (-sources.jar), documentação (-javadoc.jar), uma transferência incompleta ou uma versão para outra plataforma. "Invalid plugin.yml" e "only DEFLATED entries can have EXT descriptor" também indicam um ficheiro inadequado. "Restricted name" com "0x20" significa que o nome do plugin definido em plugin.yml contém um espaço.

Como resolver:

  1. Pára o servidor e remove da pasta plugins o JAR indicado, em Ficheiros.
  2. Transfere o JAR do plugin propriamente dito a partir da página oficial, adequado ao Paper ou ao Spigot. Os mods Fabric ou Forge não pertencem à pasta plugins.
  3. Se a transferência vier em ZIP, extrai-o no teu computador e carrega o JAR adequado.
  4. No caso de "Restricted name", utiliza uma versão corrigida pelo programador. O nome do plugin definido tem de ser corrigido; um nome de ficheiro diferente não resolve este erro.
  5. Reinicia e verifica a Consola.

Bom saber: Ao substituir o JAR, conserva os dados e as configurações do plugin existentes.

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.

PlaceholderAPI: o ficheiro da expansão não contém uma classe de expansão carregável

Este é o aspeto da mensagem:

[PlaceholderAPI] Failed to load expansion <File>.jar, as it does not have a class which extends PlaceholderExpansion

O que está por trás disto: Uma expansão do PlaceholderAPI fornece marcadores de texto adicionais. O ficheiro JAR é analisado, mas não é possível encontrar ou carregar a classe de expansão necessária. Esta expansão fica desativada. O servidor continua a funcionar; os respetivos marcadores não devolvem os valores previstos.

Como resolver:

  1. Na Consola, lê as mensagens anteriores a este erro. Outros erros de carregamento podem indicar uma dependência em falta.
  2. Em Ficheiros, verifica se o ficheiro indicado é mesmo a expansão do PlaceholderAPI pretendida. Faz uma cópia de segurança dele antes de o substituir.
  3. Volta a descarregar, a partir da fonte oficial, a expansão que corresponde à versão do PlaceholderAPI instalada. Substitui o ficheiro afetado e remove as cópias duplicadas da mesma expansão.
  4. Reinicia o servidor por completo. Depois, verifica a mensagem de arranque e um marcador fornecido pela expansão.

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.