Skip to main content
Something broke? Start here. Most connector issues fall into recognizable patterns. For the exact text of errors that the SDK produces, see Error codes reference.

Debugging workflow

When a connector fails, follow this sequence:
  1. Check the logs. What’s the error message?
  2. Inspect the output. Did the sync produce a .c1z file?
  3. Verify the configuration. Are the credentials valid?
  4. Test API access. Can you reach the target API directly?
  5. Isolate the issue. Which resource type fails?

Enable debug logging

Log levels are 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 the baton CLI to inspect what a sync produced:
The CLI has more commands for debugging:
  • baton syncs -f sync.c1z lists the syncs stored in a file.
  • baton diff -f sync.c1z compares the latest full sync in a file with the one before it.
  • baton explorer -f sync.c1z opens a local browser interface for exploring a sync.
  • baton sanitize makes a copy of a sync file with identifying data removed, which is useful when you need to share a file for a bug report.
Add -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.
The SDK stops the sync when it sees this. It doesn’t catch a token that alternates between two values. See Pagination patterns.

Authentication failed

Error: An HTTP 401 or 403 from the target API. Through uhttp, 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
Diagnostic steps:

Rate limited

Error: HTTP 429 Too Many Requests, or a slow sync Solutions:
  1. Reduce the page size. Smaller requests are less likely to trip a limit. Use the page size the SDK passes in opts.PageToken.Size where your API accepts one.
  2. Use uhttp. It turns a 429 into a gRPC Unavailable error. The SDK then waits and retries, using the API’s rate limit headers when the request passed uhttp.WithRatelimitData, and an increasing delay otherwise. The delay grows linearly, not exponentially.
  3. Limit your request rate. Pass uhttp.WithRateLimiter(rate, per) when you create the client, instead of calling time.Sleep in your builder.

Resource type mismatch

Error: Grants reference principals that don’t exist Cause: The ResourceId in a grant doesn’t match any synced resource.
Debug:
Compare the resource type IDs in the two outputs.

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
The second command shows each request and its status code.

Connection refused

Error: connection refused or no such host
If your connector has a base URL setting, point it at the right host. Run --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.
Never skip TLS verification in production.
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

If requests time out, --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-sync isn’t set. It makes the connector ignore sync tasks.
  • The connector isn’t already busy. It runs up to --task-concurrency tasks at once, and the default is 3.
  • The process is alive. Run it with --health-check and request /health, /ready, or /live on --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 logs heartbeat: 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 a debug.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.
Verify which resource types declare provisioning:
If the capability is present but provisioning still fails in daemon mode, check that the connector runs with --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

  1. RawId not set. The connector doesn’t include the RawId annotation.
  2. ID format mismatch. The connector uses a different ID format than you expected.
  3. Incorrect match_baton_id value. The Terraform resource has the wrong ID value.
  4. Case sensitivity. IDs may be case-sensitive.

Resolution

Step 1: Confirm in your code that the connector builds the resource with the RawId 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:
Step 4: Delete the duplicate and sync again.

Diagnostic commands

Getting help

If you’ve tried these steps and still have issues:
  1. Search existing issues on the connector’s GitHub repo.
  2. Check SDK issues at baton-sdk issues.
  3. 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.

Diagnostic tools