> ## Documentation Index > Fetch the complete documentation index at: https://ventstream.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Diagnose engine, VentStream Cloud, authentication, enrollment, and local development failures. ## Agents | Symptom | Cause / fix | | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Agent remains `starting`, then reports `degraded` or `failed` | Check connector credentials, [database trust configuration](/docs/guides/database-tls), source CDC prerequisites, and network policy. Amazon RDS PostgreSQL and MySQL should use `trust.provider: aws_rds`; private CAs require a mounted `ca_file`. Inspect engine logs and `ventstreamctl agents status`. | | Bootstrap skipped on restart | Retained source position means the connector resumes instead of re-scanning. Use Fleet rebootstrap for supported local state. PostgreSQL drops its slot; Neo4j, MongoDB, and MySQL remove their local cursor; Kafka consumer-group offsets must be reset through Kafka administration. | | Cloud reports an unhealthy or stale instance but the engine has no current error | The control stream or process stopped reporting. Inspect `agents status`, supervisor logs, and the pod restart count. | | Created edge "doesn't propagate" (Neo4j) | Temporal contract — the edge needs `fromDate` or the spec's `WHERE` filters it. The fan-out *did* fire (see `recomposed=N` in the log); the projection just returned nothing. | | Off-spec node change has no effect | Expected — only paths the spec declares, within `fan_out_max_hops`, propagate. | | One change recomputes the whole graph (Neo4j) | A hot (shared) endpoint isn't being filtered. Confirm `VS_NEO4J_HOT_NODE_THRESHOLD` (default 100) is above the shared node's cardinality. | | Two agents producing duplicate events | They share a source identity or state path. Give each workload a unique PostgreSQL slot, Neo4j/MongoDB/MySQL state path, MySQL server ID, or Kafka consumer group as appropriate. CDC remains single-active per pipeline. | ## VentStream Cloud and CLI | Symptom | Cause / fix | | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `auth login` cannot complete | Confirm the control-plane URL, open the printed authorization URL on the same workstation, and allow the loopback callback on `127.0.0.1`. Start a new login if the five-minute callback window expired. | | `auth status` reports an expired access token | Normal commands refresh first-party sessions automatically. Use `auth token --refresh` to force rotation; log in again if the refresh family expired or was revoked. | | Commands target the wrong organization or environment | Run `ventstreamctl config show`, then use `config set-org` and `config set-env` with the intended context. | | A lifecycle command returns `queued` | The control plane accepted durable work but the agent has not completed it. Use `--wait` or inspect `ventstreamctl operations describe --attempts`. | | A selected revision is not running | Selection activates and delivers configuration, but it does not resume a paused pipeline. Check the apply operation, then run `ventstreamctl pipelines resume --wait`. | | Configuration delivery waits with no agent | Confirm the deployment is enrolled and connected with `ventstreamctl agents status`. The pending operation is delivered after a matching agent connects, subject to its expiry. | | Agent enrollment fails immediately | The grant expired, was already consumed or replaced, or targets another deployment. Create a new single-use grant. For private gateway trust, also verify the configured CA Secret; public Cloud gateways use WebPKI trust. | | Agent enrolled but cannot open the control stream | Check outbound gateway reachability, system time, certificate validity, deployment identity revocation, and the supervisor's persisted identity state. | ## Build / local | Symptom | Cause / fix | | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Compose service cannot bind a host port | Another process or Compose project owns the configured port. Override the corresponding `VENTSTREAM_DEMO_*_PORT` value instead of stopping unrelated software. | | `ventstream` is not found after installation | Add `~/.local/bin` to `PATH`, or set `VENTSTREAM_INSTALL_DIR` and add that directory. | | `--validate-config` reports a missing environment reference | Export the variable named by the `env:...` value. Validation resolves references but does not open source or sink connections. | | `pg_drop_replication_slot` errors on resync | The slot is still in use by a running agent. Stop the agent first, or let the engine's own drain path drop it. | ## Reading the recompose log The Neo4j engine logs `recomposed=N` per event. A healthy distribution: * **many `recomposed=1`** — edge create/delete ops, correctly scoped. * **a few large values** — node-property changes on shared nodes (legitimate cascades — the embedded value changed everywhere). If you see large values for *edge* ops, a hot endpoint isn't being filtered — check the threshold.