Debugging workflow
When a connector fails, follow this sequence:- Check the logs. What’s the error message?
- Inspect the output. Did the sync produce a
.c1zfile? - Verify the configuration. Are the credentials valid?
- Test API access. Can you reach the target API directly?
- Isolate the issue. Which resource type fails?
Enable debug logging
debug, info, warn, and error. The default is info. --log-format is json or console, and the default depends on whether the output is a terminal. Add --log-path <file> to write logs to a file. Every flag also works as an environment variable, such as BATON_LOG_LEVEL=debug.
At the debug level, uhttp logs every HTTP request. Search the logs for these messages:
Each message includes
http.method, http.status_code, duration, and the URL host and path. To print response bodies as well, set BATON_DEBUG_PRINT_RESPONSE_BODY to any non-empty value. Be careful: bodies can contain sensitive data.
Inspect sync output
Use thebaton CLI to inspect what a sync produced:
baton syncs -f sync.c1zlists the syncs stored in a file.baton diff -f sync.c1zcompares the latest full sync in a file with the one before it.baton explorer -f sync.c1zopens a local browser interface for exploring a sync.baton sanitizemakes a copy of a sync file with identifying data removed, which is useful when you need to share a file for a bug report.
-o json for machine-readable output.
Common errors
Pagination loop detected
Error:listing resources failed: next page token unchanged ... - likely a connector bug. Entitlements and grants have matching messages.
Cause: Your List, Entitlements, or Grants method returned the same non-empty token it received.
Authentication failed
Error: An HTTP 401 or 403 from the target API. Throughuhttp, these arrive as gRPC Unauthenticated and PermissionDenied errors, and the SDK doesn’t retry them.
Causes:
- Invalid or expired credentials
- Missing required scopes or permissions
- Wrong API endpoint
Rate limited
Error: HTTP429 Too Many Requests, or a slow sync
Solutions:
-
Reduce the page size. Smaller requests are less likely to trip a limit. Use the page size the SDK passes in
opts.PageToken.Sizewhere your API accepts one. -
Use
uhttp. It turns a 429 into a gRPCUnavailableerror. The SDK then waits and retries, using the API’s rate limit headers when the request passeduhttp.WithRatelimitData, and an increasing delay otherwise. The delay grows linearly, not exponentially. -
Limit your request rate. Pass
uhttp.WithRateLimiter(rate, per)when you create the client, instead of callingtime.Sleepin your builder.
Resource type mismatch
Error: Grants reference principals that don’t exist Cause: TheResourceId in a grant doesn’t match any synced resource.
Empty sync results
Error: The sync finishes but produces no resources Causes:- The API returns empty results, often because of a permissions issue
- Pagination starts past the end of the data
- A filter, such as
--sync-resource-types, is too restrictive
Connection refused
Error:connection refused or no such host
--help to see whether it does.
TLS certificate errors
Error:x509: certificate signed by unknown authority
For testing only: The SDK has no flag that skips TLS verification. If your connector adds one, it builds the HTTP client with uhttp.WithTLSClientConfig. See Insecure TLS for local testing.
For production: Add the certificate authority to the system’s trust store. On Linux, Go also reads a CA bundle from the SSL_CERT_FILE environment variable:
Performance issues
Slow sync
--http-timeout-seconds raises the HTTP timeout. The default is 300 seconds, and the maximum is 1800.
Memory issues
Daemon mode issues
In daemon mode, a connector polls C1 for tasks. It needs both--client-id and --client-secret.
Task polling failures
Errors:failed to get token: <status>, invalid client id, runner: error getting next task, or c1_api_task_manager: startup Hello failed
The connector connects to C1 over TLS. To point it at a different C1 host, set
BATON_C1_API_HOST.
Connector not receiving tasks
Symptom: The daemon runs but never processes anything. Check:- The connector is registered in C1, and the client ID matches it.
- A sync is scheduled.
--skip-full-syncisn’t set. It makes the connector ignore sync tasks.- The connector isn’t already busy. It runs up to
--task-concurrencytasks at once, and the default is 3. - The process is alive. Run it with
--health-checkand request/health,/ready, or/liveon--health-check-port(default 8081).
Tasks that start and then stop
While a task runs, the connector reports progress to C1 at an interval that C1 sets. If it can’t report progress ten times in a row, it stops the task and logsheartbeat: failed after 10 attempts. If C1 cancels the task, the connector logs heartbeat: task was cancelled by server. Check the connector’s network path to C1.
Debug logs requested by C1
C1 can ask a connector to capture debug logs for a task. The connector writes them to adebug.log file in its temporary directory and uploads that file with the sync.
Provisioning issues
Grant and revoke failures
Error:resource type <type> does not have provisioner configured
Cause: C1 sent a grant or revoke for a resource type whose builder doesn’t implement provisioning.
--provisioning. See Implementing provisioning.
Duplicate objects after sync
Symptom
After a sync, you see duplicate resources in C1: one created through Terraform or the API and a separate one discovered by the connector.Causes
- RawId not set. The connector doesn’t include the
RawIdannotation. - ID format mismatch. The connector uses a different ID format than you expected.
- Incorrect
match_baton_idvalue. The Terraform resource has the wrong ID value. - Case sensitivity. IDs may be case-sensitive.
Resolution
Step 1: Confirm in your code that the connector builds the resource with theRawId annotation. See ID correlation recipes.
Step 2: Check what ID the connector uses:
Some connectors don’t use the native ID for every resource type. For example, a Databricks group’s ID is a compound path, not the bare Databricks group ID. See per-connector ID formats for the full list.
Step 3: Update Terraform to use the exact match:
Diagnostic commands
Getting help
If you’ve tried these steps and still have issues:- Search existing issues on the connector’s GitHub repo.
- Check SDK issues at baton-sdk issues.
- Open a new issue with:
- The connector name and version
- The full error message
- Debug logs, with credentials removed
- Steps to reproduce
Quick reference
Debug flags
Many connectors also have an endpoint or base URL flag. Run
--help to find out.