Troubleshooting

Troubleshooting

Start with structured diagnostics:

pnpm exec shamoo doctor --json
pnpm exec shamoo build

Then inspect the Minecraft server log, the deployed shamoo-plugin.json, shamoo.metadata.json, and the exact watched-root installation.

Runtime JAR does not load

• Confirm java -version reports Java 21.
• Confirm the host is Linux x86-64; the bundled Javet/Node native runtime does not currently support other platforms.
• Install the Paper JAR only on Paper and the Velocity JAR only on Velocity.
• Paper must be 1.21.8 build 55 for the pinned Runtime, especially when packets are enabled. Velocity is pinned to 3.4.0, with build 566 used by the process fixture.
• Verify sha256sum --check SHA256SUMS and gh attestation verify before replacing artifacts.
• Remove neither the JAR's embedded dependencies nor its generated platform descriptors.

Plugin is not discovered

• Deploy to <paper>/plugins/ShamooRuntime/plugins or <velocity>/plugins/shamooruntime/plugins, not the general server plugins/ directory.
• The watched root must contain one direct child directory per installation, and that child must contain shamoo-plugin.json.
• Do not symlink the candidate, descriptor, bundle, or metadata. Discovery rejects symlinks and path escapes.
• Wait for the stability window and watcher debounce. Repeated writes can keep a candidate unstable.
• Check duplicate descriptor names; all duplicate-identity candidates are rejected.
• On Velocity, verify the -Dshamoo.plugins.directory=... value belongs before -jar and is absolute when intended.

shamoo deploy says no target is configured

Set deploy.paper/deploy.velocity in shamoo.config.json or pass an override:

pnpm exec shamoo deploy \
  --paper /srv/paper/plugins/ShamooRuntime/plugins

Configured targets must exist as directories and be writable for doctor; deploy creates a missing target but still needs permission to write it. Source/output paths are different: they must remain relative to the project root and may not escape through symlinks.

Package manager tries npm or returns 404

The npm registry is not the canonical v0.1.0-rc.1 source and publication is not assumed. Download every ShamooTS .tgz from the GitHub prerelease, verify it, and install all tarballs together:

pnpm add /absolute/path/to/shamoo-ts-v0.1.0-rc.1/*.tgz

A single tarball can leave synchronized @shamoo/* dependencies unresolved and trigger a registry query. If assets are unavailable, use the source-pack fallback in Installation.

Compiler asks for an injection token

Interfaces, type aliases, primitives, and type-only imports have no runtime identity. Create and use an explicit token:

import { Inject } from '@shamoo/decorators';
import { createToken } from '@shamoo/di';

interface Store { get(key: string): string | undefined }
const STORE = createToken<Store>('plugin store');

class Consumer {
  public constructor(@Inject(STORE) readonly store: Store) {}
}

Even valid constructor metadata is not yet instantiated by the bundled adapter; deployed component classes currently need zero constructor dependencies.

PERMISSION_REQUIRED or unsupported import

• Add every Node builtin to permissions.builtins using its canonical node:* name.
• Sensitive builtins also need the corresponding filesystem/network/workers/child-process request.
• @shamoo/paper-nms requires permissions.nms: true.
• @shamoo/paper-packets requires permissions.packets: true plus Runtime operator gates.
• node:module, node:repl, node:vm, native addons, arbitrary packages, and unresolved dynamic import paths cannot run in the current host.
• Network, workers, child processes, native filesystem access, and native addons remain denied by Runtime even when metadata requests them.

PLATFORM_LEAK

Paper and Velocity entrypoints are analyzed independently. Move @shamoo/paper*, Bukkit, Paper, or NMS imports behind the Paper entrypoint; move @shamoo/velocity* imports behind the Velocity entrypoint. Shared files reachable from both must be platform-neutral. See First Plugin.

Decorator is discovered but has no effect

The bundled adapter currently calls handlers directly. It does not construct the DI graph, bind decorated parameters, evaluate Requires, or run guards, pipes, interceptors, filters, and validators. It also ignores scheduled delays/repetition, command aliases/subcommand trees, and custom event priority options. This is expected current behavior, not fixed by adding more decorator metadata. See Core Decorators and Custom Decorators.

Event handler throws ... is not a function

Generated Paper/Velocity interfaces describe pinned JVM APIs, but current deployed callbacks receive copied payloads only:

• Paper: { type, asynchronous }
• Velocity: { type }

Do not call methods such as getPlayer() on those callback payloads. Use supported data-only command/host operations or an embedding adapter that explicitly implements a richer safe carrier.

Entry point context or DI value is undefined

Use zero-argument definePaperEntrypoint/defineVelocityEntrypoint hooks. The bundled adapter does not currently pass the typed entrypoint context. It also does not publish a PaperScheduler DI token or instantiate constructor dependencies.

Scheduled task runs immediately or once

The current adapter registers Paper tasks as global work and Velocity tasks at delay 0. It does not interpret Scheduled, Interval, or Timeout timing metadata. Folia region/entity work requires an explicitly supplied PaperScheduler; see the folia example.

Packet handler is denied or lacks packet fields

Check all three gates: project permissions.packets, Paper Runtime packets.enabled, and the exact descriptor ID in packets.allowed-plugins. Confirm Paper 1.21.8 build 55. The current JS adapter supplies packet metadata and supports pass/cancel only; it does not expose the generated live packet object or typed replacement. See Packet Decorators.

shamoo dev appears not to preserve state

dev rebuilds and redeploys a complete installation. Runtime replaces the plugin generation; it is not JavaScript module hot swapping. State transfer requires descriptor opt-in and both runtime generations implementing the optional hot-state contract. Ordinary class fields reset.

Build runs out of memory

The generated platform declarations are large:

NODE_OPTIONS=--max-old-space-size=8192 pnpm check

Use Node 22 or newer and pnpm 10 or newer. Run pnpm codegen:check rather than manually editing generated files.

Source maps do not resolve

Deploy the .js.map beside each generated bundle and deploy the matching shamoo.metadata.json. Do not rename descriptor-relative paper/index.js, velocity/index.js, or map paths. Rebuild and redeploy them as one candidate so Runtime's stable inventory cannot mix generations.

Security issue

Do not open a public issue. Use the repository's private GitHub vulnerability reporting and include affected versions, reproduction, impact, and mitigation without credentials or active target data. The in-process runtime is defense in depth, not a complete sandbox; isolate mutually untrusted code at the process/container boundary.