Skip to main content
Support

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 "Q&A Specialist." 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

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. qoderwake status shows the service is running, the URL output by qoderwake portal --no-open opens successfully, and the Web Console page finishes loading. If restart refuses to execute because the login is invalid, and you only need local mode: 
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.
qoderwake whoami displays the expected account, Gateway authentication passes in network diagnostics, and the target remote page loads normally.

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.
After sending a minimal test message, the task transitions from queued to running and eventually returns a reply or a clear error.

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.
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.

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.
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.

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.
After clearing filters, the target task is found, its status matches the original task details, and you can jump to the source page normally.

Knowledge-base sources are unavailable

  1. Confirm that the account can open the Notebook and that the source exists, has finished processing, and can be viewed.
  2. Verify the binding from both the knowledge-base home page and Waker details.
  3. Start a new conversation, test a question with a definite answer, and ask the Waker to use the target Notebook.
  4. If the answer is still inaccurate, remove outdated or conflicting versions and retest.
Verification: The Waker accurately answers facts present in the sources and follows the current version. If signed out, complete account authorization again. If a shared Notebook cannot be edited, check collaborator permissions.

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.
The connector shows as available, the system can discover and list tools, and the minimal test task successfully calls and returns a result. 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: 
Error: internal panic: chat_permission_grant flag redefined: params
Clear the DWS tool cache in the user directory following the DWS usage guide: 
rm -rf ~/.dws/cache/default_default/tools/*
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.
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 itemCheck first
Gateway authenticationWhether the login is valid, the account is correct, and the system time is accurate
Machine registrationWhether the local service is running, the device has completed registration, and the account is consistent
Work return linkWhether 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. After fixing, re-run diagnostics — Gateway authentication, machine registration, and Work return link all show as passed, and the previously failing remote operations succeed.

Update downloaded but version unchanged

  1. Go to "Settings" → "Update Application" and confirm the update has been installed.
  2. Restart the service: 
    qoderwake restart
  3. Run qoderwake status, then go to "Update Application" to verify the version.
After restarting, the running version matches the installed version and the page no longer displays "Restart needed." If you only run qoderwake update without restarting, the current service may still be using the old version.

View logs and submit feedback

Locate logs: Default main log location: 
${QODERWAKE_HOME:-$HOME/.qoderwake}/logs/qoderwake.log
Choose a retrieval method based on the problem: 
# 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: 
qoderwake feedback --email "your-email" --message "problem description"
When related to a specific Waker, add --waker-id <wakerId>. The command returns a feedback id, indicating successful submission. Save this ID for future reference when following up. Submitting feedback requires a valid login. The problem description parameter is --message.

Q&A Specialist issues

The bot is in the group, but no pairing request appears

  1. In Quick Configuration on the Q&A Specialist home page, confirm that the target bot is connected and enabled.
  2. Confirm that the bot is in the target group, then @mention it again with a message.
  3. Return to Pairing Requests, verify the group and bot, and approve the request.
  4. If no request appears, go to IM > Conversation Management > Add Pairing. Update DWS and search manually, or generate a pairing code valid for 10 minutes and send it to the group.
Verification: the target group shows "Paired," test messages reach the Q&A Specialist, and the messages appear in Q&A Records.

Private expert assistance fails with a 403 IP allowlist error

The error may include: 
HTTP 403 - IpNotInWhiteList
Resolution:
  1. Identify the DingTalk application reporting the error and obtain the actual egress IP address of the QoderWake server.
  2. Add that egress IP to Security Settings for the application in the DingTalk Open Platform.
  3. Wait for the change to take effect and retest. Do not use a private address from the local machine.
Verification: IpNotInWhiteList no longer appears and the target expert receives the request.

Answers exceed the business scope or mix in unrelated guidance

  1. Review the knowledge bases bound to the Q&A Specialist and remove sources unrelated to the current business or containing conflicting guidance.
  2. Use separate knowledge bases for different products or business policies and confirm source processing is complete.
  3. Retest with an in-scope question, an out-of-scope question, and a question not covered by the sources.
Verification: questions with reliable sources follow the current guidance; out-of-scope or unsupported questions state uncertainty or enter expert assistance.

The answer is abnormal, but the page shows no direct error

  1. In Q&A Records, locate the question by group, user, and time, and determine whether processing stopped at knowledge retrieval, expert assistance, or reply generation.
  2. If needed, open the execution record for the Q&A workflow and inspect business logs, the final return value, and raw events.
  3. Based on the failure point, correct the bot, group pairing, knowledge base, expert configuration, or Q&A workflow, and then retest in the test group.
Verification: known questions are answered correctly, unknown questions state uncertainty or request assistance, and Q&A Records identify the processing stage. Other common symptoms:
SymptomResolutionVerification
Image question is misunderstoodAdd a text question and context and point out the relevant region or field; provide the source data for complex chartsThe answer addresses the specified region
A DingTalk document link shows 404 after knowledge-base importExport the restricted document to a supported file, upload it to the Notebook, and validate againProcessing completes and the Waker can answer from the file
Get Started
Working with Wakers
Capabilities
Best Practices
Configuration
Support