Frequently asked questions

Find the symptom below. Check status and logs before retrying an operation.

A node is offline

Run with the actual service account's permissions on the node host:

gamex daemon status
gamex daemon doctor

status shows local service state and available connection information. doctor checks Docker connectivity. Nodes initiate their connection to Panel. Check the Panel address, system time, TLS, proxy WebSocket forwarding, and node logs. For a custom installation configuration, pass the same --config path.

For detailed steps, see Connect a node.

A node is online, but a server will not start

1. Check Docker availability, image architecture, capacity, and port conflicts.
2. Confirm the Workspace is deployed, its startup command is valid, and your account has write access.
3. Read the exit reason in the primary service console and check scripts, runtime paths, and configuration files.
4. Start or restart the service after fixing the cause, then inspect service diagnostics. The primary service can exit while its container remains running.

Shell and file management remain available after stopping the primary service. Only /workspace survives a container rebuild. Diagnose the cause before rebuilding. See Manage servers.

A service is running, but players cannot connect

1. Check the game's listening port, TCP/UDP protocol, and workspace port mapping.
2. Check the host firewall, cloud security group, and router forwarding.
3. Try joining from the network players actually use.

Node diagnostics only show observations from the node host. The AI public-port check runs from the Panel server and tests TCP at the specified public IP. A UDP probe also cannot prove that players can join the game.

Shell still works after stopping, and environment edits do not apply immediately

Stopping the primary service differs from stopping its Workspace container. Existing Shell sessions can continue. Variable and Secret changes apply to new processes, without replacing an existing process's environment. Open a new Shell or restart the primary service when needed. See Manage servers.

A long command is still running, but earlier output is missing

Read recent output from the original Shell session before running the command again. A recent portion may remain after older output is removed. If the session has ended and been cleaned up, check the task log or the program's own logs.

No AI models are selectable, or a saved model is unavailable

Ask a super administrator to check credentials, plan, model discovery, and enablement in Agent Management. Visibility does not mean enabled; plans without presets initially require manual model enablement. Assign available models to model roles and reselect disabled or removed models in conversations.

For connection or stream inactivity timeouts, check the provider request timeout; changes apply to new tasks. AI_PROVIDER_EMPTY_RESPONSE means empty-response recovery was exhausted. AI_PROVIDER_INVALID_RESPONSE indicates an invalid response or tool-call format. Inspect request records, upstream status, and model capabilities before retrying. See AI assistant and automation.

AI cannot read server files, or a task is waiting for approval

Use a workspace conversation for files, logs, and Shell. After a management-panel conversation hands off a task, open the target workspace to check progress; the original conversation remains available. Check current Workspace access and conversation mode, then reopen pending questions or approvals from their notice.

Approval cannot expand account permissions. Full access retains required human approvals. Unattended schedules end with a policy error when questions, Secrets, or approvals cannot be handled safely. Failure, interruption, or archiving pauses queued tasks. Select Resume queue in Panel after resolving the issue.

A plugin cannot be installed, or its panel does not appear

Check revocation, signatures, compatibility, configuration, and permissions. Some plugins have no panel. For those that do, authorize the target Workspace in the installation's runtime settings. Browser resource policy must also allow required origins.

For detailed steps, see Install and manage plugins.

QQ Bot connects, but does not reply or execute tasks

Check the connection mode, bot credentials and platform event configuration, Workspace authorization, external-conversation binding, and binding owner's current access. A successful connection does not establish a valid binding or available model. Handle approvals requiring strong verification in Panel. QQ messaging windows and platform limits also apply.

See QQ Bot for setup, commands, and diagnostics.

Panel requires a database migration after an upgrade

Startup checks migration state without automatically migrating an existing database. Back up the database, configuration, and encryption key; stop the old Panel; then run migrations with the new version and the same configuration. Run only one Panel per database. See Upgrade and backup for source and Compose commands.

Memory remains after deleting a conversation

Memory is stored separately and is not removed with a conversation. Open Memory to edit or clear the current account's personal documents. Before binding an external chat, remove any content that should not be shared. See AI assistant and automation.

Where should security issues be reported?

Use the private reporting route in the repository's SECURITY.md for credential or production issues.

For plugin boundaries, see Plugin permissions and security.