Troubleshooting
Use this page to diagnose the most common OpenBox n8n integration issues.
Node Not Appearing After Install
- Confirm Settings → Community Nodes shows
n8n-nodes-openbox-hookas installed. - Restart n8n — some installs require a restart before the node appears in the node panel.
- Search "OpenBox" in the node panel to find OpenBox: Agent.
- If you built a custom n8n image, confirm the package was installed before the image was built and that
N8N_CUSTOM_EXTENSIONS(or your image's install path) includes it.
"No Chat Model Connected" Error
The node throws this before governance runs at all. Drag a language model sub-node (for example "OpenAI Chat Model") into the node's Chat Model input — it is a required connection.
"No Prompt Found On Item" Error
This means the node could not resolve a user message for that item.
- If Source for Prompt is set to Connected Chat Trigger Node,
confirm a Chat Trigger is connected and the incoming item actually has a
chatInput(ortext/message/input/query/prompt) string field. - Otherwise, switch to Define Below and set the Prompt field explicitly.
Credential Test Fails
- Confirm the API Key is correct and not expired.
- If Require signing is enabled for the agent, confirm both Agent DID and Agent Private Key are set — partial identity configuration will fail requests.
- Confirm the runtime running n8n can reach
https://core.openbox.ai.
No Runs In The Dashboard
If your agent executes but no run appears in OpenBox:
- Confirm the OpenBox API credential is attached to the OpenBox: Agent node (it is optional at the type level, so it's easy to forget).
- Confirm the workflow actually executed the node — check n8n's Executions tab.
- Verify the API key belongs to the same agent you are viewing in OpenBox.
- Check n8n's logs for network errors reaching
core.openbox.ai.
Tool Calls Do Not Show A Tool Type
There is currently no tool_type_map equivalent in the node UI —
ToolStarted / ToolCompleted events are sent without a tool_type tag.
Target policies on tool_name instead. See
Event Model.
Governance Blocks Or Halts The Agent
Governance errors mean OpenBox policy enforcement is working.
| Error | Meaning |
|---|---|
GovernanceBlockedError | A model call, tool call, or run was blocked |
GovernanceHaltError | The whole run should stop, including approval rejection or expiry |
GuardrailsValidationError | A configured guardrail matched restricted content |
All three surface as one NodeOperationError. To investigate:
- Open the OpenBox Dashboard
- Go to Agents
- Open the agent and the latest run
- Review the event timeline and the policy or guardrail message
See Error Handling for handling patterns, including Continue On Fail.
Approval Requests Do Not Appear
If your policy should require approval but no request appears:
- Confirm the policy returns
REQUIRE_APPROVAL, notBLOCK. - Confirm the policy targets the correct event type and tool name.
- Check the run timeline to see whether another policy blocked the event first.
- Confirm the agent is connected to the expected OpenBox organization.
Agent Run Silently Stops After A Tool Call
If a Tool sub-node returns an HTTP error body as a string instead of
throwing (this is common with n8n's HTTP Request Tool on non-2xx
responses), the agent node detects it and stops with
Tool "<name>" failed: <message> instead of looping further. This is
expected behavior, not a governance block — check the tool's underlying HTTP
call for the actual failure.
Missing HTTP Or Database Telemetry
- Confirm the code path actually performs HTTP or database I/O during the agent run.
- Confirm the operation happens inside the active node execution, not in an unrelated node earlier in the workflow.
- Remember n8n's own internal Postgres connection is filtered out by design — only your workflow's own database calls appear.
Next Steps
- Integration Walkthrough - Review the full wiring path
- Configuration - Check credential fields and current defaults
- Error Handling - Handle governance exceptions safely