Skip to main content

Troubleshooting

When something goes wrong in Worka, the first job is to place the problem correctly.

Most user-visible failures come from one of a small number of causes:

  • the workspace is still building
  • a connection or approval is missing
  • a pack or tool path failed
  • a view is present but not really live
  • a device or runtime path is unavailable

If you can tell which category you are looking at, the next action usually becomes obvious.

Start with the workspace status​

Before you inspect anything else, check:

  • whether the workspace is still provisioning
  • whether there are pending approvals
  • whether a required connection is missing
  • whether a pack is still building, failed, or was never attached
  • whether the blocked area is the main view or a supporting one

Those checks tell you whether the workspace is waiting, blocked, or actually broken.

Symptom: the workspace looks empty​

If the workspace opens but feels empty, one of three things is usually true:

  • the workspace is still being built
  • the first useful view has not been published yet
  • the main view was published but depends on a connection or pack that is still missing

Do not assume “empty” means “nothing is happening.” Check whether the workflow or activity history shows active work.

Symptom: a view renders but does nothing useful​

If a view appears but has no real data or working actions, the issue is usually below the UI.

Common causes:

  • the tool path behind the view is failing
  • the required service connection is absent
  • the pack was discovered but not attached correctly
  • the workspace is still waiting on a capability dependency

Treat “screen exists” and “feature is live” as separate things.

Symptom: Worka keeps waiting​

Waiting is not always a failure.

The workspace may be waiting on:

  • approval
  • a service connection
  • a pack build or release
  • a retry after a transient failure
  • device availability for a task that cannot run everywhere

The workspace should tell you which wait you are seeing. If it only says “loading,” that is a product visibility problem.

Symptom: a task should have continued, but it did not​

If a task stops unexpectedly, check:

  • whether it is blocked on approval
  • whether a hook deferred or failed the step
  • whether the next AI team member or tool never became eligible to run
  • whether the required data never appeared in the step output

This is where the workflow history matters. A stop should have a visible reason.

Symptom: browser or computer use will not run​

If browser or desktop automation does not run, check:

  • whether the capability is enabled for this workspace
  • whether the right device is available
  • whether the mode or permission needed for the task has been granted
  • whether the task is waiting on approval because the capability is sensitive

These failures are often about access or environment, not the view itself.

Symptom: a connected service still does not work​

If a service shows as connected but the workspace still cannot use it, check:

  • whether the connection belongs to this workspace
  • whether the access level is sufficient for the requested action
  • whether the pack using the service is healthy
  • whether the failing action is still approval-gated

A connection alone does not guarantee that every path using it is complete.

When to escalate​

If the workspace state still does not explain the failure clearly, you have reached the operator boundary.

That is when someone needs to look at:

  • pack release state
  • workflow history in more detail
  • runtime failures
  • broker or network issues
  • policy decisions and approval records

You should not have to become an operator to use Worka, but you should be able to tell when operator help is required.