# Troubleshooting This guide covers common errors you may encounter when working with Sling API specifications and how to resolve them. ## Common Error Messages ### Endpoint Errors | Error Message | Cause | Solution | | -------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------- | | `endpoint not found: X` | The endpoint name doesn't exist in the spec | Check spelling, run `sling conns discover CONN_NAME` to see available endpoints | | `endpoint is disabled in spec` | Endpoint has `disabled: true` | Remove the `disabled` field or set it to `false` | | `duplicate endpoint name generated: X` | Dynamic endpoints created the same name twice | Ensure your dynamic endpoint name template produces unique names | ### Queue Errors | Error Message | Cause | Solution | | ---------------------------------------- | --------------------------------------------- | --------------------------------------------------------------- | | `did not declare queue X in queues list` | Queue is used in a processor but not declared | Add the queue name to the top-level `queues:` list in your spec | ### Authentication Errors | Error Message | Cause | Solution | | -------------------------------------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------- | | `could not authenticate` | Authentication configuration is invalid | Verify secrets, tokens, and credentials in your env.yaml | | `unsupported OAuth2 flow: X` | Invalid OAuth2 flow type specified | Use one of: `client_credentials`, `authorization_code`, `device_code` | | `client_secret is required for client_credentials flow` | Missing OAuth2 client secret | Add `client_secret` to your connection secrets | | `authorization_url or derived URL is required for authorization_code flow` | Missing authorization URL | Add `authorization_url` to your authentication config | | `device_auth_url or derived URL is required for device_code flow` | Missing device auth URL | Add `device_auth_url` to your authentication config | | `failed to authenticate` | Authentication request failed | Check API credentials, verify auth URLs, enable `--trace` for details | ### Response Processing Errors | Error Message | Cause | Solution | | ------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------- | | `need at least 2 lines to build records from csv` | CSV response is empty or only has a header | Ensure the API returns a header row plus at least one data row | | `could not evaluate jmespath` | Invalid JMESPath expression | Test your expression with an online JMESPath tester; check for syntax errors | | `error converting record to map` | Response data structure is unexpected | Verify the JMESPath returns an array of objects, not primitive values | ### Request & Iteration Errors | Error Message | Cause | Solution | | ----------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------ | | `empty request url` | URL is not set or evaluated to empty | Check `request.url` and ensure state variables are defined | | `loop expression is not an array or a queue` | `iterate.over` doesn't evaluate to an array | Ensure the expression returns an array or references a valid queue | | `invalid 'into' variable` | Wrong format for iteration variable | Use format `state.variable_name` (e.g., `state.current_id`) | | `request loop into value must be state.` | Iteration variable not in state namespace | Prefix with `state.` (e.g., `state.item` not just `item`) | ### Processor Errors | Error Message | Cause | Solution | | ---------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------- | | `empty response processor expression` | Processor has no `expression` field | Add an `expression` to the processor | | `empty response processor output` | Processor has no `output` field | Add an `output` destination (e.g., `record.field`, `state.var`) | | `invalid aggregation type` | Unknown aggregation specified | Use one of: `maximum`, `minimum`, `first`, `last`, `collect` | | `cannot write aggregated value to queue` | Trying to aggregate into a queue | Remove `aggregation` when writing to queues; queues receive individual values | | `env. and context.store. outputs require aggregation type` | Missing aggregation for env/store outputs | Add an `aggregation` field (e.g., `aggregation: last`) | ### Rule & Retry Errors | Error Message | Cause | Solution | | ----------------------------------- | ------------------------- | --------------------------------------------------------------------------- | | `number of attempts exhausted: X/Y` | All retry attempts failed | Check API availability, increase `max_attempts`, or review backoff strategy | | `rule met to fail: ` | A fail rule was triggered | Check response status code; verify authentication and request parameters | ### License Errors | Error Message | Cause | Solution | | ------------------------------------------------------------ | -------------------------------- | ------------------------------------------------------------- | | `please use the official sling-cli release for reading APIs` | CLI Pro token missing or invalid | Get a CLI Pro token from [slingdata.io](https://slingdata.io) | ## Debugging Techniques ### Using Debug and Trace Flags ```bash # Basic debugging - shows request flow and status codes sling conns test MY_API --endpoints endpoint_name --debug # Detailed tracing - shows full request/response details sling conns test MY_API --endpoints endpoint_name --trace ``` **Debug output includes:** * API requests being made * Response status codes * Record counts * Pagination details * State variable changes **Trace output adds:** * Full request headers and parameters * Response headers * JSON response bodies (truncated for large responses) * Detailed expression evaluation * Auth token refresh events > **Warning:** The `--trace` flag may expose sensitive information like authorization tokens. Don't share unredacted logs. ### Testing Individual Endpoints ```bash # List all available endpoints sling conns discover MY_API # Test a specific endpoint sling conns test MY_API --endpoints users # Test multiple endpoints sling conns test MY_API --endpoints users,orders,products # Test with pattern matching sling conns test MY_API --endpoints "user_*" ``` ### Limiting Data During Testing Set an environment variable to limit records: ```bash export SLING_TEST_ENDPOINT_LIMIT=10 sling conns test MY_API --endpoints large_endpoint ``` Or use the `limit` property in your endpoint: ```yaml response: records: jmespath: "data[]" limit: 10 # Only process 10 records during testing ``` ## Authentication Troubleshooting ### OAuth2 Issues **Token not refreshing:** * Verify `authentication_url` is correct * Check that scopes are sufficient * Tokens are stored in `~/.sling/api/tokens/{connection_name}.json` - delete to force re-auth **Authorization code flow not working:** * Ensure `redirect_uri` matches your OAuth app configuration * Check `authorization_url` is correct * Verify scopes include required permissions **Device code flow timing out:** * The user must complete authorization in the browser within the time limit * Verify `device_auth_url` is correct ### Static/Bearer Token Issues * Verify the token hasn't expired * Check token format (some APIs require `Bearer` prefix, others don't) * Ensure secrets are correctly referenced: `{secrets.api_key}` ## Pagination Troubleshooting ### Not fetching all pages Check your `stop_condition`: ```yaml pagination: stop_condition: "length(response.records) == 0" # Stops when empty # OR stop_condition: 'jmespath(response.json, "has_more") == false' # API-specific ``` Use trace to see pagination flow: ```bash sling conns test MY_API --endpoints paginated_endpoint --trace ``` Look for: * `stop_condition` evaluation results * `next_state` changes between requests ### Cursor/offset not updating Ensure `next_state` expressions reference the correct response fields: ```yaml pagination: next_state: cursor: '{jmespath(response.json, "pagination.next_cursor")}' # OR offset: '{state.offset + state.limit}' ``` ## JMESPath Troubleshooting ### Common JMESPath Issues **Empty records array:** * Verify the path to your data in the response JSON * Test with `[*]` to get all top-level elements * Use `--trace` to see the actual response structure **Syntax errors:** * Use an [online JMESPath tester](https://jmespath.org/) to validate expressions * Remember: property names with special characters need quotes: `"content-type"` * Arrays use `[]` suffix: `data.items[]` **Examples:** ```yaml # Top-level array jmespath: "[*]" # Nested array jmespath: "data.results[]" # Filter records jmespath: "users[?status=='active']" # Project specific fields jmespath: "data[].{id: id, name: full_name}" ``` ## Getting Help If you're still having issues: 1. **Check the logs** with `--trace` for detailed error information 2. **Verify your spec** syntax by running `sling conns test` 3. **Test the API directly** with curl or Postman to rule out API issues 4. **Search existing issues** on [GitHub](https://github.com/slingdata-io/sling-cli/issues) 5. **Ask the community** on [Discord](https://discord.gg/q5xtaSNDvp) 6. **Contact support** at --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.slingdata.io/concepts/api-specs/troubleshooting.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.