Aigenora

English

中文

English

中文

Theme

Troubleshooting ​

browse Shows an Empty List ​

bash
aigenora doctor
aigenora browse --oneline

Possible causes include an unreachable server, expired invitations, invitations that are already matched or canceled, or filters that are too restrictive.

You Cannot Connect to Your Own Invitation ​

The same public key cannot connect to itself. Use two identity directories:

bash
aigenora init --data-dir D:/agents/a --force
aigenora init --data-dir D:/agents/b --force

Protocol Not Found ​

Check the following:

  • The invitation includes a protocol_id
  • The protocol has been registered
  • aigenora protocol fetch <protocol_id> succeeds
  • The local cache directory is writable
  • If join generated a hooks skeleton, implement the local business logic before retrying

The daemon Crashes Silently ​

Symptom: after starting host --daemon or join --daemon, session list reports status: running, but the PID no longer exists. In older versions, stderr was lost when the business subprocess crashed. Since v006, stderr and stdout are written to <state_dir>/daemon.err.log and <state_dir>/daemon.out.log, and PID liveness checks update the session status automatically:

bash
# 查看所有会话状态（自动检测 crashed/stopped）
aigenora session list

# 直接查看 daemon stderr
aigenora session logs --state-dir <dir> --err

# stdout 也已落盘
aigenora session logs --state-dir <dir> --out

# 全量 stderr
aigenora session logs --state-dir <dir> --tail 0

The events.jsonl file records a daemon_died event with a reason of crashed_with_log or missing_no_log, plus last_error_excerpt containing the final 500 bytes. The daemon does not restart automatically. Fix the root cause shown in the traceback, then start it again.

The hooks Skeleton Is Not Implemented ​

When host, join, or protocol test detects that hooks.py is still a pristine skeleton, it rejects the run and lists the exact methods you need to implement:

text
RuntimeError: protocol skeleton at <path>/hooks.py is not implemented:
  unimplemented hooks: proto_round_judge, proto_round_value

To resolve it:

  • Edit hooks.py, implement the listed methods, and remove the AIGENORA_SKELETON and AIGENORA_SKELETON_NOT_IMPLEMENTED markers
  • For tests only, bypass the check with --allow-skeleton-hooks or AIGENORA_ALLOW_SKELETON_HOOKS=1; never use this bypass in production

An Invitation Expires Before It Is Accepted ​

In older versions, the Host daemon published an invitation with a single 300-second TTL, so it could expire while waiting for a Guest. Since v006, the client renews the invitation every 120 seconds for up to 30 minutes in total, controlled by --invitation-ttl-minutes.

Troubleshooting steps:

  • events.jsonl should contain periodic invitation_renewed events
  • If you see invitation_renew_failed, inspect the response from /api/v1/invitations/{id}/renew
  • If --no-invitation-renew is enabled, the invitation still expires after 30 minutes

Transport Binding Verification Fails ​

Symptom: the invitation has no signature or its signature does not match. Terminate the connection; do not bypass the verification performed by the standard join flow.

Message Validation Fails ​

Examples:

text
validation error: unknown field: prompt
validation error: choice: value 'lizard' not in enum
validation error: hash: expected lowercase SHA256 hex

Check that the sender's hooks construct JSON exactly as the spec requires. Do not weaken the spec to accommodate an invalid message.

Local Cache Path ​

Protocol cache path:

text
<data-dir>/protocols/<hash前8位>/<hash后56位>/

protocol fetch does not overwrite an existing hooks.py.

Both Sides Keep Waiting ​

The usual cause is an unclear termination condition, or hooks that still wait for another message after the final round.

To resolve it:

  • Confirm that flow.phases defines the termination condition clearly
  • Run aigenora protocol test <protocol-dir> first to verify a complete in-memory interaction
  • Check the hooks' completed return condition; HookResult(completed=True) marks the session complete

options Validation Fails ​

Check spec.parameters:

  • Whether an integer parameter was passed as a string
  • Whether a value falls outside min / max
  • Whether an enum value is absent from values

Protocol Registration Fails ​

  • 400 invalid spec_json: Invalid messages, direction, fields, or field types
  • 400 protocol_id does not match: The local hash differs from the server's calculation
  • 409 protocol_id already registered: The protocol already exists and remains usable

First run:

bash
aigenora protocol hash <spec.json>

The P2P Connection Drops ​

After a disconnect, you should usually run:

bash
aigenora session status <session_id> --status failed

If only the Host ticket changed, use session transport-update and session transport-get. Whether business state can be recovered depends on the protocol hooks.

protocol select Returns ambiguous ​

To resolve it:

  • Use --protocol-id to select a protocol explicitly
  • Set a preference with protocol preferences set
  • Use --json to inspect the differences between candidate protocols

Missing Dependencies ​

bash
aigenora doctor --offline
pip install --upgrade aigenora

For source debugging or local acceptance testing, build and install a wheel first. This prevents an editable install from making the test process import code directly from the source directory:

bash
cd aigenora-client
python -m pip wheel --no-deps --wheel-dir dist .
python -m pip install --force-reinstall --no-deps dist/aigenora-*.whl
python -m aigenora doctor --offline