Skip to content
Lingchu Bot

Troubleshoot common issues

Resolve the most common local startup, adapter, and group-management issues. Each entry describes the symptom, the cause, and the fix.

Installation and startup

Section titled “Installation and startup”

Dependency installation fails

Section titled “Dependency installation fails”

Confirm Python and uv are available and meet the version requirements:

Terminal window
python --version   # must be 3.13
uv --version

Install dependencies with:

Terminal window
uv sync --frozen

Boolean configuration errors

Section titled “Boolean configuration errors”

An in_containers 配置错误 error means a Boolean was written in a non-JSON form. NoneBot configuration files only accept standard JSON lowercase true / false.

Correct:

LINGCHU_IN_CONTAINERS=true

Incorrect:

LINGCHU_IN_CONTAINERS=True

Bot cannot connect to the platform

Section titled “Bot cannot connect to the platform”

Check, in order:

  1. Whether the service for the enabled adapter has started (default is OneBot V11).
  2. Whether NoneBot and the enabled adapter connection settings match.
  3. Whether the account, network, firewall, and platform permissions are usable.

Adapter selection

Section titled “Adapter selection”

LINGCHUAdapter is unset

Section titled “LINGCHUAdapter is unset”

When LINGCHUAdapter is unset, Lingchu Bot enables ~onebot.v11 by default. Ensure NoneBot has loaded the OneBot V11 adapter.

PlatformAdapterNotLoadedError

Section titled “PlatformAdapterNotLoadedError”

The selected adapter was not loaded or registered by NoneBot. Either load the matching adapter or change LINGCHUAdapter to one that is already loaded.

Multiple adapters for the same platform

Section titled “Multiple adapters for the same platform”

Do not explicitly configure multiple adapters for the same platform. For example, LINGCHUAdapter = "~onebot.v11+~another_adapter" fails immediately.

Unknown adapter registered at runtime

Section titled “Unknown adapter registered at runtime”

Extra registered same-platform adapters do not create a conflict. Lingchu Bot treats unselected adapters as disabled. Unknown adapters that do not belong to any platform profile are not considered enabled; message storage writes their platform field as unknown.

Group management

Section titled “Group management”

Mute or unmute command fails

Section titled “Mute or unmute command fails”

Mute, unmute, and whole-group mute depend on platform permissions. When they fail, check:

  1. Whether the bot is in the target group.
  2. Whether the bot has the required management permission (admin or owner).
  3. Whether the target user can be operated on by the bot (e.g. not a higher-ranked admin).
  4. Whether the enabled adapter API reports a network error or rejected operation.

Feedback appears in the wrong language

Section titled “Feedback appears in the wrong language”

Check whether LINGCHU_LOCALE is set to a supported catalog such as zh_CN or en_US. Unknown text falls back to the original message.

CI or local checks

Section titled “CI or local checks”

Check commands fail

Section titled “Check commands fail”

Read the failing command and line number, then fix only the related scope. Common checks:

Terminal window
uv run -m ruff check . --output-format=github
uv run -m ruff format --check .
uv run -m pyright
uv run -m ty check --output-format github
uv run -m pytest