Debugging

Gode reports problems through Godot’s output panel, TypeScript diagnostics, and native runtime logs. The fastest debugging path is to separate installation, compilation, runtime, dependency, and export failures.

Script output

Use Godot’s print helpers when a message should appear in Godot’s Output panel:

import { GD } from "godot";

GD.print("player state", this.state);
GD.printerr("failed to load profile", profileId);

console.log() and console.error() are still available as Node console APIs. Treat them as terminal diagnostics: they are useful when Godot is launched from a terminal, but Gode does not guarantee that they are mirrored into Godot’s Output panel.

For runtime-only issues, start Godot from a terminal so Node/V8 warnings, console.* output, and native extension messages are visible.

TypeScript diagnostics

When compilation fails, Gode reports TypeScript diagnostics in the Godot output panel. Common causes include:

• Importing Godot classes without from "godot".
• Referencing Node globals without installing and enabling Node types.
• Using a local import path that TypeScript cannot resolve.
• Excluding scripts accidentally through tsconfig.json.
• Depending on declaration files that are not included in the project.

Confirm the plugin contains addons/gode/tsc/lib/typescript.js; release packages include it.

Runtime exceptions

JavaScript exceptions crossing into Godot are reported as Godot script errors. When a failure happens after await, in a signal callback, or inside a timer, read the full terminal output to preserve async stack and runtime context.

Recommended pattern for critical entry points:

import { GD } from "godot";

async function runTask(): Promise<void> {
  try {
    await doWork();
  } catch (error) {
    GD.printerr(error);
    throw error;
  }
}

Log context near the failure, then rethrow when Godot should treat it as a script error.

Package resolution

If an npm package cannot be found:

1. Confirm the Godot project root contains package.json.
2. Confirm dependencies are installed under root node_modules.
3. Confirm the script imports the package by its package name, not a generated cache path.
4. Confirm export keeps export.npm.exportDependencies and includeNodeModules enabled.
5. For wasm, data files, or native side assets, add explicit export handling through extraIncludePaths or your own pipeline.

Native extension loading

If the plugin fails to load:

• Confirm the target platform is supported.
• Confirm addons/gode/binary/gode.gdextension exists.
• Confirm the matching platform binary exists under addons/gode/binary/<platform>/<arch>/.
• Restart the editor after replacing binaries.
• Check Godot’s terminal output for dynamic library load errors.

When reporting bugs, include the Gode version, Godot version, operating system, target export platform, and the smallest project or script that reproduces the issue.