Agents
| Symptom | Cause / fix |
|---|---|
Agent remains starting, then reports degraded or failed | Check connector credentials, database trust configuration, 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 <operation-id> --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 <pipeline> --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 logsrecomposed=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).