Registration Issues

The agent's zynd agent run reports registered, but you can't find it via zynd search or zynd resolve.

0. Confirm registration actually succeeded

Look at the run logs for these lines (Python SDK):

[registry] entity not registered yet — sending POST /v1/entities
[registry] registered zns:d52a64d115b84388459f40d9d913da7f

If you see the first line but not the second, registration failed mid-way. The error message is in the line right after.

If you don't see either, the SDK may have skipped registration silently — usually because agent.start() was never called or there's a config error before that point.

1. Searching the wrong registry

zynd auth whoami       # shows the registry the CLI uses
zynd search "..."      # uses the same registry

If the CLI's registry differs from the agent's registry_url, you'll see no results. Either:

• Update agent.config.json → registry_url to match what your CLI uses, or
• Pass --registry <url> to zynd search.

2. The agent is inactive

Search filters out inactive entities by default. Check status:

zynd info --entity-id zns:<your-id> --json | grep status

If status: "inactive", your heartbeat isn't running. See Heartbeat Issues.

To see inactive entities in search:

zynd search "..." --include-inactive
# or in the SDK:
search_entities(..., status="any")

3. Signature rejected

Look in the registration error response for signature_invalid. Causes:

• The agent keypair doesn't match the public key the registry has on file (re-derive: zynd keys derive --index <N>).
• The developer proof is built from a developer key not registered as a developer on this registry. Run zynd auth login against the registry your agent points to.
• Clock skew — the message's timestamp is more than max_clock_skew_seconds (default 60s) off the registry's clock. Sync NTP.

4. Wrong entity type filter

Searches default to entity_type = "agent". If you registered a service (zns:svc:...), it won't show up unless you filter explicitly:

zynd search "..." --type service

5. Federation lag

If the registry you registered on isn't zns01.zynd.ai, results take up to ~30 seconds to gossip across the mesh. Add --federated to your search and wait a moment:

zynd search "..." --federated

6. Handle / FQAN already taken

A 409 Conflict from POST /v1/handles or POST /v1/names means someone else has the handle or the entity name under that handle. Pick another:

curl https://zns01.zynd.ai/v1/handles/your-name/available

7. Restricted-mode registry

Some registries (private deployments) run with onboarding_mode: restricted. Self-registration is disabled — you need an admin to approve via POST /v1/admin/developers/approve.

Check GET /v1/info — onboarding_mode: "restricted" means you need to be approved first.

8. Ngrok / tunnel returned a non-https URL

The registry rejects entity_url values that aren't HTTPS. If your tunnel handed you http://..., set ZYND_ENTITY_URL to the HTTPS version explicitly.

9. Container has no internet

If the agent runs inside a container or behind a strict firewall and can't reach the registry's domain, you'll see DNS or TCP errors at boot, but zynd agent run keeps trying. From inside the container:

curl https://zns01.zynd.ai/health   # should print 200
curl -i https://zns01.zynd.ai/v1/info

If those fail, the container has no outbound HTTPS. Fix the firewall or the container's network mode.

Diagnostic playbook

# 1. Is the registry reachable?
curl https://zns01.zynd.ai/v1/info

# 2. Is the entity actually there?
curl https://zns01.zynd.ai/v1/entities/zns:<your-id>

# 3. Is it active?
curl https://zns01.zynd.ai/v1/entities/zns:<your-id> | jq .status

# 4. Does the FQAN resolve?
curl https://zns01.zynd.ai/v1/resolve/<handle>/<name>

# 5. Search by exact name (no semantic ranking)
curl -X POST https://zns01.zynd.ai/v1/search \
  -d '{"query":"<name>","max_results":5}'

If step 2 returns 200 but step 5 returns nothing, the search index is stale — restart your agent or wait ~5 min for the bloom rebuild.

See also

• Heartbeat Issues — if your registration succeeded but the agent shows as inactive.
• Common SDK Errors — if registration never even fires.