Workflow: Troubleshooting Playbooks

Last validated: 2026-05-11

Use these playbooks to quickly isolate auth, routing, schema, or payload issues.

Playbook 1: Auth and Token Issues

Symptoms:

• unauthorized from gRPC/HTTP
• CLI commands suddenly failing after earlier success

Steps:

1. Re-authenticate.

dodil login <service_account_id> <service_account_secret>

2. Retry lightweight command.

dodil vbase db list

3. Validate direct API token usage.

grpcurl -insecure -H "authorization: Bearer $TOKEN" -d '{}' "rpc.dev.dodil.io:443" dodil.vbase.v1.VBaseService/HealthCheck

Playbook 2: db use Succeeds but Data Commands Fail

Symptoms:

• db use works
• collection / data / index commands fail to connect

Steps:

1. Re-run context selection.

dodil vbase db use <service_id>

2. Check selected endpoint values in ~/.config/dodil/config.yaml.
3. Validate tenant endpoint health.

dodil vbase status

4. If still failing, retrieve access again via API.

grpcurl -insecure -H "authorization: Bearer $TOKEN" -d '{"service_id":"<service_id>"}' "rpc.dev.dodil.io:443" dodil.vbase.v1.VBaseService/GetServiceAccess

Playbook 3: Search Returns Empty or Invalid Results

Symptoms:

• no search hits when data exists
• output field missing expected ID values

Steps:

1. Confirm schema and index.

dodil vbase collection show <collection_name> --db <db_name>

2. Verify search flags match schema names.

• --vector-field should match collection vector field.
• --id-field should match primary key or desired output field.

3. Confirm vector dimension equals collection schema dimension.

Playbook 4: RunCommand Payload Parse Errors

Symptoms:

• invalid JSON in input_payload
• deserialization errors to Milvus request type

Steps:

1. Validate input_payload JSON separately.
2. Ensure quotes are escaped inside outer JSON string.
3. Start with a minimal method (ShowCollections) before complex payloads (Search).

Known requirement:

• include dbname metadata for DB-scoped methods.

Playbook 5: Cluster API over HTTP Behaves Unexpectedly

Symptoms:

• HTTP GetCluster route mismatch
• task endpoint semantics look inconsistent

Cause:

• known proto annotation drift for some cluster endpoints.

Fix:

• use gRPC calls for cluster lifecycle methods as primary path.