Troubleshooting

Browser extension hydration warnings

If the browser console reports server/client attribute differences containing bis_skin_checked or bis_register, an extension has modified the HTML before React attached its event handlers. These attributes are not emitted by the Playbook.

Open the same URL in a clean browser profile with extensions disabled. If the warning disappears, identify the extension that inserts those attributes and restrict its site access for the local preview, then reload. An incognito window only helps if the extension is not allowed to run there.

Suppressing warnings throughout the page would hide real mismatches and does not remove the injected attributes. If the error persists in a clean profile, capture the new mismatch and URL; it may have a different cause.

For connection failures, see access token troubleshooting and MCP setup.

The CLI cannot find my project

Run commands from the project directory or pass --config /path/to/.octonode.yaml. For a new project, use octonode init .octonode.yaml --name my-project. Avoid --force unless you intend to replace an existing manifest.

If you are working from a source checkout, run the built CLI at packages/cli/dist/index.js. The node-authoring runtime is TypeScript on Node.js 24.

A signature is stale

Run octonode scan --check --config .octonode.yaml to confirm drift. After reviewing the source changes, run octonode scan --config .octonode.yaml to update signatures, then validate again. In Studio, use Compile after source edits.

Scan can mark a missing source as orphaned instead of deleting its workflow connections. Restore the source or deliberately remove the obsolete node and edges.

A node fails input validation

Inspect the node's required fields and types. Check the names of incoming ports, fixed input values, and expressions. Supply valid JSON: numbers and booleans should use their JSON types rather than quoted strings unless the schema expects strings.

A workflow has missing outputs or skipped nodes

Open the execution and find the first failing node. Inspect its error and input before changing downstream nodes. Review timeout and retry settings, service credentials, and the selected environment. Use --json on a CLI run to inspect the full status and trace.

Replay runs the selected node again and may repeat external writes. Choose a test environment or safe input when diagnosing a node with external effects.

If a generated native node exits without output, check that the project can resolve @octonode/plugin-runtime. The CLI being available does not install that runtime dependency into a separate project. The first-workflow tutorial uses a directory inside the built checkout so it can resolve the workspace SDK.

HTTP 200 contains a failed run

HTTP 200 means the execution was admitted. Inspect the JSON status and error; only status: "ok" indicates a successful workflow outcome. Preserve the complete URL copied from Start, including workspace and project parameters. See HTTP execution.

A plugin is visible but unavailable in my workflow

Confirm that it is attached to the selected project, not only cached in the workspace library. Retry a failed dependency installation, configure required credentials, and inspect the node's contract before running it again.

My settings file does not change Studio appearance

Run octonode settings validate --file octonode.yml to validate the settings document. The current settings loader and CLI do not apply appearance, layers, or views to Studio yet. Studio's project Settings tab manages metadata separately. See Configuration reference.