turbo-monitor-debug
Turbo Pipeline Monitoring & Debugging Reference
CLI commands, error patterns, and troubleshooting reference for Turbo pipelines. For interactive pipeline diagnosis (running commands, checking logs, walking through fixes), use /turbo-doctor instead.
Quick Reference
| Action | Command |
|---|---|
| List pipelines | goldsky turbo list |
| View live data | goldsky turbo inspect <name> |
| Inspect specific node | goldsky turbo inspect <name> -n <node> |
| View logs | goldsky turbo logs <name> |
| Follow logs | goldsky turbo logs <name> --follow |
| Logs with timestamps | goldsky turbo logs <name> --timestamps |
| Last N lines | goldsky turbo logs <name> --tail N |
| Logs since N seconds ago | goldsky turbo logs <name> --since N |
Live Inspect TUI Shortcuts
| Key | Action |
|---|---|
Tab/→, Shift+Tab/← |
Next/prev tab |
1-9 |
Jump to tab number |
j/k / ↑/↓ |
Scroll |
g/Home, G/End |
Top/bottom |
Page Up/Page Down |
Scroll by page |
/ → Enter |
Search |
n / N |
Next/prev match |
Esc |
Clear search |
d |
Toggle definition |
w |
Open web dashboard |
e |
Open web editor |
q / Ctrl+C |
Quit |
Shift + mouse |
Select and copy text |
Auto-Reconnection
The TUI automatically reconnects when the pipeline is updated, paused, resumed, or temporarily unavailable. It displays "Reconnecting..." and preserves previously received data. The TUI has a 30-minute timeout — if the pipeline remains unreachable for 30 minutes, it closes automatically.
Error Pattern Reference
Detailed error patterns and solutions are in the
data/folder.
| File | Contents |
|---|---|
error-patterns.json |
All known error patterns with causes and solutions |
Data location: data/ (relative to this skill's directory)
Log Analysis Script
Use the helper script to quickly analyze pipeline logs:
./scripts/analyze-logs.sh <pipeline-name>
./scripts/analyze-logs.sh <pipeline-name> --tail 100
The script checks for common error patterns and reports findings with recommendations.
Common Error Patterns
| Error Pattern | Likely Cause | Fix |
|---|---|---|
connection refused |
Database unreachable | Check network/firewall settings |
authentication failed |
Wrong credentials | Update secret with correct credentials |
secret not found |
Missing secret | Create secret with goldsky secret create |
SQL syntax error |
Invalid transform SQL | Fix SQL in YAML and redeploy |
duplicate key |
Primary key collision | Ensure unique primary key in transform |
script transform error |
TypeScript runtime failure | Check script logic, null handling, return types |
dynamic_table error |
Backend connection issue | Verify dynamic table secret/table exists |
WASM execution failed |
Script crash in sandbox | Debug script — check for undefined access |
handler timeout |
External HTTP endpoint slow | Increase timeout_ms or fix handler endpoint |
Script Transform Issues
| Issue | Fix |
|---|---|
undefined property access |
Add null checks: input.field ?? '' |
| Wrong return type | Ensure returned object matches schema exactly |
| Missing return fields | All schema fields must be present in returned object |
invoke is not a function |
Ensure script defines function invoke(data) |
| BigInt errors | Use BigInt() constructor, not direct number literals |
Dynamic Table Issues
| Issue | Fix |
|---|---|
| Table not found | Create the table in PostgreSQL before deploying |
| No matches from check | Verify data exists in the backing table |
| Stale data | For postgres backend, verify rows are actually there |
| Memory pressure | Large in_memory tables → switch to postgres backend |
Common Issues Quick Reference
| Symptom | Likely Cause | Quick Fix |
|---|---|---|
| No data flowing | start_at: latest |
Wait for new data or use earliest |
| Auth failed | Wrong credentials | Update secret with correct password |
| Connection refused | Network/firewall | Check host, whitelist Goldsky IPs |
| Storage exceeded | Neon free tier (512MB) | Upgrade plan or clear data |
| SQL error | Bad transform syntax | Validate YAML first |
Troubleshooting
| Issue | Action |
|---|---|
| Can't connect to inspect | Check pipeline is running with goldsky turbo list |
| Logs are empty | Pipeline may be new; wait for data or check start_at |
| TUI disconnects | Auto-reconnects within 30 min; check pipeline status |
| Can't find pipeline | Verify correct project with goldsky project list |
Related
/turbo-doctor— Interactive diagnostic skill that uses this reference to troubleshoot pipelines/turbo-builder— Build and deploy new pipelines
More from goldsky-io/goldsky-agent
turbo-builder
Build and deploy new Goldsky Turbo pipelines from scratch. Triggers on: 'build a pipeline', 'index X on Y chain', 'set up a pipeline', 'track transfers to postgres', or any request describing data to move from a chain/contract to a destination (postgres, clickhouse, kafka, s3, webhook). Covers the full workflow: requirements → dataset selection → YAML generation → validation → deploy. Not for debugging (use /turbo-doctor) or syntax lookups (use /turbo-pipelines).
38turbo-pipelines
Turbo pipeline YAML reference and architecture guide. Covers: YAML field syntax (start_at, from, version, primary_key), source/transform/sink configuration, validation errors, resource sizing (xs–xxl), architecture decisions (dataset vs kafka, streaming vs job, fan-out vs fan-in, sink selection, pipeline splitting). Triggers on: 'what does field X do', 'what fields does a postgres sink need', 'what resource size', 'should I use kafka or dataset', 'how to structure my pipeline'. For writing transforms, use /turbo-transforms. For end-to-end building, use /turbo-builder.
38turbo-doctor
Diagnose and fix broken Goldsky Turbo pipelines interactively. Triggers on: pipeline in error state, stuck starting, connection refused, not getting data, duplicate rows, missing fields, slow backfill, or any named pipeline misbehaving. Runs logs/status commands, identifies root cause, and offers fixes. For CLI syntax or error pattern lookup without an active problem, use /turbo-operations instead.
34secrets
Use this skill when a user wants to store, manage, or work with Goldsky secrets — the named credential objects used by pipeline sinks. This includes: creating a new secret from a connection string or credentials, listing or inspecting existing secrets, updating or rotating credentials after a password change, and deleting secrets that are no longer needed. Trigger for any query where the user mentions 'goldsky secret', wants to securely store database credentials for a pipeline, or is working with sink authentication for PostgreSQL, Neon, Supabase, ClickHouse, Kafka, S3, Elasticsearch, DynamoDB, SQS, OpenSearch, or webhooks.
33datasets
Use this skill when the user needs to look up or verify Goldsky blockchain dataset names, chain prefixes, dataset types, or versions. Triggers on questions like 'what\\'s the dataset name for X?', 'what prefix does Goldsky use for chain Y?', 'what version should I use for Z?', or 'what datasets are available for Solana/Stellar/Arbitrum/etc?'. Also use for chain-specific dataset questions (e.g., polygon vs matic prefix, stellarnet balance datasets, solana token transfer dataset names). Do NOT trigger for questions about CLI commands, pipeline setup, or general Goldsky architecture unless the core question is about finding the right dataset name or chain prefix.
33turbo-transforms
Write SQL, TypeScript, and dynamic table transforms for Turbo pipelines. Covers: decoding EVM logs with _gs_log_decode, filtering/casting blockchain data, UNION ALL for combining events, TypeScript/WASM transforms (invoke function), dynamic lookup tables (dynamic_table_check), transform chaining, and Solana decoding. Triggers on: 'decode Transfer events', 'write a SQL transform', 'filter by contract', 'TypeScript transform', 'dynamic table', 'UNION ALL'. For pipeline YAML structure, use /turbo-pipelines. For end-to-end building, use /turbo-builder.
32