River
Ctrl K
Open River

Troubleshooting

Troubleshooting Basics

When something feels off, run through these checks before deeper debugging.

1) Verify intent and mode#

  • Confirm whether you're in Edit, Plan, or Ask in SpaceChat.
  • Ask mode does not mutate state — if you expected an action, switch to Edit.
  • Plan mode produces a plan but stops there — switch to Edit to execute.

2) Verify context#

  • Confirm the right entities are open in your Windows.
  • The AI uses your open Windows and selection as immediate context.
  • For complex tasks, attach entities explicitly with @ in SpaceChat.

3) Verify automation boundaries#

  • If a task should be automatic, confirm the Schedule or Trigger exists for the relevant Agent.
  • Open AutomationsApp → Agents → your Agent → check that triggers are enabled.
  • If a Job failed, confirm outputs were written to the expected entity location — open the Job from the Runs tab.

4) Verify discoverability#

  • Use Search (Cmd K) to find the output entity.
  • Use Activity to confirm whether the action ran at all.
  • Activity will show whether it was a human or AI action, and link to the Job record.

5) Trace the data flow#

If you expected something to be in River and it isn't:

  1. Did the integration ingest it? Check Settings → Integrations → status.
  2. Did an entity get created? Search for it; check the relevant Group.
  3. Was it indexed? Search for words from inside the content.
  4. Did the expected event fire? Look in Activity around the right timestamp.
  5. Did downstream surfaces update? Check Notifications, Smart Folders, Agent runs.

See Data Flow Basics for the full chain.

6) Check the Job, if it ran#

If you expected an Agent or Workflow to do something, every run is a Job:

  • Open AutomationsApp → Runs.
  • Find the Job by Agent name or time range.
  • Click it to see the full execution record — every tool called, every output written.
  • Failed Jobs include error messages and the state at failure.

Common gotchas#

  • Wrong Dataspace — if you switched Dataspaces, your Agents/integrations from the other one aren't visible. Check the switcher in the top-left.
  • Stale browser tab — if a desktop change isn't appearing in the browser, refresh the tab.
  • Token expired — integrations occasionally need re-auth. The integration card will say "disconnected" if so.
  • Quiet hours — Schedules respect your User Profile's work hours. Disable quiet hours if a job seems to be skipping.

Escalating#

If you've checked all of the above and still can't explain it, capture:

  • What you expected
  • What actually happened
  • The mode (Edit / Plan / Ask), Space, and Dataspace
  • The relevant entity IDs (right-click → Copy ID)
  • A timestamp

That short packet makes debugging dramatically faster, whether you're asking on the community forum or a teammate.