> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> QoderWake troubleshooting guide organized by symptom, covering the console, login, Wakers, automated tasks, WakerFlow, knowledge base, connectors, network diagnostics, updates, logs, and feedback.

This chapter is organized by failure symptom. You can jump to the relevant heading from the table of contents or search the page for keywords such as "console," "login," "automated task," "WakerFlow," "knowledge base," "connector," "update," or "Qmate."

Troubleshoot in this order: local service, then login and network, then device and Waker, then task configuration, then external capabilities. Change only one thing at a time and retest immediately. If the issue persists, collect logs, error messages, and the time the problem occurred.

## Console fails to open

```bash theme={null}
qoderwake status
qoderwake start --open
qoderwake portal --no-open
qoderwake restart
```

Check the service status, start the service, and obtain the actual access URL in sequence. If it still does not open, restart. Do not rely solely on a bookmarked fixed port.

<Tip>
  `qoderwake status` shows the service is running, the URL output by `qoderwake portal --no-open` opens successfully, and the Web Console page finishes loading.
</Tip>

If `restart` refuses to execute because the login is invalid, and you only need local mode:

```bash theme={null}
qoderwake restart --force
```

This flag starts in local mode. If you need remote capabilities, log in again first.

## Login or remote capabilities unavailable

1. Run `qoderwake whoami` to check the account. If not logged in or the account is incorrect, run `qoderwake login`.
2. After logging in, verify the account again and run network diagnostics.
3. If remote devices are still not visible, confirm they use the same account and refresh the device page.

<Tip>
  `qoderwake whoami` displays the expected account, Gateway authentication passes in network diagnostics, and the target remote page loads normally.
</Tip>

## Waker not responding or task running indefinitely

1. Check the status on the task board. If it shows "Action needed," go to the original task to handle it.
2. If queued or running for a long time, verify the device is online, the service is running, and the machine is not asleep.
3. Open the original task to view errors and send a minimal test message. If it still fails, check the directory, model, connector, and permissions.

<Tip>
  After sending a minimal test message, the task transitions from queued to running and eventually returns a reply or a clear error.
</Tip>

## Automated task not running

1. Confirm the task is enabled and verify the time, timezone, event/API request, validity period, and run count.
2. When using a local directory, confirm the device is powered on, the service is running, and the machine is not asleep at trigger time.
3. Check the run history to distinguish between "not triggered" and "ran but failed." After fixing, run manually first, then wait for a real trigger.

<Tip>
  A new record appears in the run history with the expected start time and trigger method, and you can open the full result of that run.
</Tip>

## WakerFlow stuck, failed, or results incomplete

1. Open "Execution Records" and confirm the current Phase, Worker, and whether it is waiting for user input.
2. If waiting for input, go to the run details to respond. If a Worker failed, view the error, Result, and raw events.
3. Verify run parameters, Waker, knowledge base, connector, and permissions. Use business logs to locate the phase, but judge results by Worker Result and the final return value.
4. After fixing, click "Run" in the upper-right corner to re-execute.

<Tip>
  All required Workers in the new run complete successfully, the execution record shows completed, and the final return value contains the full fields specified by the flow.
</Tip>

## Task board shows no tasks or status not updating

1. Clear all filters (type, group, Waker, status) and switch between list and swimlane views.
2. For group tasks, expand the parent task and go back to the original entry to confirm the task was actually created.
3. Re-enter the board. If source reading fails, run network diagnostics and check permissions.

<Tip>
  After clearing filters, the target task is found, its status matches the original task details, and you can jump to the source page normally.
</Tip>

## Connector unavailable

1. Go to Waker details → "Connectors" and check the configuration, authorization, connection status, and tool list.
2. Go to the Waker's "Permissions" to confirm the relevant tools are allowed.
3. Create a minimal test task that only calls that connector.

<Tip>
  The connector shows as available, the system can discover and list tools, and the minimal test task successfully calls and returns a result.
</Tip>

Connectors are managed centrally in the "Connectors" section of Waker details. Do not paste tokens or keys into conversations, knowledge bases, or logs.

### DWS: chat\_permission\_grant redefined

If the error message matches the following exactly:

```text theme={null}
Error: internal panic: chat_permission_grant flag redefined: params
```

Clear the DWS tool cache in the user directory following the DWS usage guide:

```bash theme={null}
rm -rf ~/.dws/cache/default_default/tools/*
```

<Warning>
  Only execute this when the error message matches exactly. Do not modify the directory in the command, and do not treat this as a general fix for all connector issues.
</Warning>

Stop DWS test tasks before executing. After clearing, refresh the connector page, re-detect, and complete a read-only verification.

## Network diagnostics failed

Go to "Settings" → "Network Diagnostics," run the full diagnostics, and address items by failure type:

| Failed item            | Check first                                                                                                                 |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Gateway authentication | Whether the login is valid, the account is correct, and the system time is accurate                                         |
| Machine registration   | Whether the local service is running, the device has completed registration, and the account is consistent                  |
| Work return link       | Whether the device is online, and whether the corporate network or firewall is blocking long connections or return requests |

Also check system time, DNS, corporate network, firewall, and security software. If necessary, switch networks to retest and record the failure summary.

<Tip>
  After fixing, re-run diagnostics — Gateway authentication, machine registration, and Work return link all show as passed, and the previously failing remote operations succeed.
</Tip>

## Update downloaded but version unchanged

1. Go to "Settings" → "Update Application" and confirm the update has been installed.
2. Restart the service:

```bash theme={null}
qoderwake restart
```

3. Run `qoderwake status`, then go to "Update Application" to verify the version.

<Tip>
  After restarting, the running version matches the installed version and the page no longer displays "Restart needed."
</Tip>

<Note>
  If you only run `qoderwake update` without restarting, the current service may still be using the old version.
</Note>

## View logs and submit feedback

### Locate logs

Default main log location:

```text theme={null}
${QODERWAKE_HOME:-$HOME/.qoderwake}/logs/qoderwake.log
```

Choose a retrieval method based on the problem:

```bash theme={null}
# Last 200 warn-level and above log entries
qoderwake log --level warn --limit 200

# Search by keyword
qoderwake log --keyword "keyword" --limit 200

# Search by traceId or sessionId
qoderwake log <traceId>
```

To continuously watch new logs, use `qoderwake log -f`. The positional argument `traceId`, `--trace-id`, and `--keyword` can only be used one at a time. Add `--clean` for simplified output.

### Collect evidence

Record the time and timezone of occurrence, version and OS, task name or ID, reproduction steps, error message, and `traceId/sessionId`. Do not submit credentials.

### Submit feedback

```bash theme={null}
qoderwake feedback --email "your-email" --message "problem description"
```

When related to a specific Waker, add `--waker-id <wakerId>`.

<Tip>
  The command returns a `feedback id`, indicating successful submission. Save this ID for future reference when following up.
</Tip>

<Note>
  Submitting feedback requires a valid login. The problem description parameter is `--message`.
</Note>