K
KoladrDocs
Sign in

Troubleshooting

Answers to common questions and issues you may encounter while setting up and running Koladr.

Why is my run not appearing?

If your agent starts a run but it does not appear in the dashboard, check the following:

  • API key is correct. Verify the key in your environment variables matches a key in Settings → API Keys.
  • Agent ID is correct. The agent ID in your SDK initialization must match a registered agent in the workspace.
  • Network connectivity. Your agent must be able to reach the Koladr API. Check for firewall rules or proxy issues.
  • Check the response. The startRun() call returns a run object. If it throws an error, the SDK will provide details about what went wrong.

✦Debug with logging

Add temporary logging around your Koladr SDK calls to capture the full request and response. This is the fastest way to identify integration issues.

Why is my action being blocked?

An action is blocked when a policy with the "block" effect matches the action request. To diagnose:

  1. Go to the Runs page and find the run that contained the blocked action
  2. Open the run detail view
  3. Look at the action entry — it will show which policy blocked it
  4. Review the policy conditions to understand why it matched

If the block is incorrect, update the policy conditions in Policies to narrow when it applies. If the block is correct, update your agent logic to handle the blocked status gracefully.

Why is my action stuck in pending?

A pending action is waiting for an approver to review it. The most common reasons for long pending times:

  • No approvers available. Ensure at least one user with the Admin or Approver role is actively monitoring the queue.
  • Approvers are unaware. Make sure your team knows to check the Approvals page regularly.
  • Too many pending actions. If the queue is consistently long, consider adjusting policies to auto-allow more low-risk actions.

Actions do not time out automatically. They remain pending until an approver takes action.

What if a user has no workspace?

New users who sign up without an invitation are prompted to create a workspace during onboarding. If a user somehow completes sign-up without a workspace:

  • They will be redirected to the onboarding flow on their next login
  • An admin from an existing workspace can invite them, which will add them to that workspace

Every user must belong to at least one workspace to use the dashboard.

What if an approval cannot be resolved?

If an approval is stuck and no one can decide:

  • Reject it. If in doubt, rejecting is the safe choice. The agent can resubmit if needed.
  • Review the run. Open the linked run to understand the full context. This often makes the decision clear.
  • Escalate.If the action is outside anyone's comfort zone, escalate to an admin who can investigate further.

Why is my connector execution failing?

If an approved action fails to execute through a connector:

  • Check connector status. Go to Connectors and verify the provider is connected and healthy.
  • Token expiry. OAuth tokens can expire. Reconnect the provider to refresh them.
  • Invalid parameters. The action parameters may not match what the external service expects. Check the incident details.
  • Service outage. The external service may be temporarily unavailable. Retry later.

Why is my API key not working?

If you are getting authentication errors:

  • Verify you are using the complete key (no extra spaces or truncation)
  • Check that the key has not been deleted in Settings → API Keys
  • Ensure you are using the key for the correct workspace
  • If the key was recently created, wait a few seconds for propagation

How do I safely test before production?

Recommended approach for safe testing:

  1. Register a separate agent for testing (e.g. "Support Bot (Dev)")
  2. Use a test API key, not your production key
  3. If connectors are in demo/stub mode, they will simulate execution without real side effects
  4. Create test policies that mirror your production policies
  5. Run through complete workflows: start run → log events → request actions → end run
  6. Verify the dashboard shows accurate data for your test runs
  7. Test the approval workflow with a colleague acting as approver

ℹStaging workspace

For the most thorough testing, create a separate staging workspace with its own agents, policies, and connectors. This gives you a fully isolated environment to test in.

Why did my run end with an error?

If a run shows an "errored" status:

  • Check the run detail view for the error summary (set in endRun())
  • Review the event timeline to see the last events before the error
  • Check your agent's logs for the corresponding error
  • If the error is from a Koladr SDK call, the error type will tell you the cause (auth, validation, rate limit, etc.)

Getting Help

If you cannot resolve an issue using this guide:

  • Check the relevant documentation section for your feature area
  • Review the run and incident detail views for diagnostic information
  • Contact the Koladr support team with the specific run ID, action ID, or incident ID so we can help quickly

You have reached the end of the Koladr documentation. Return to the Overview or dive into any section from the sidebar.