Troubleshooting
This page describes common error scenarios you may encounter when using the Generator API and provides guidance on how to resolve them. Error messages are designed to be descriptive and include actionable steps to help you address the issue.
Error Scenarios
Connectivity & Integration Errors
- Host/Port Issues: Could not resolve the host or connect to the specified port. Please check your hostname and port settings.
- SFTP Connection: Connection to the SFTP server failed. This may be due to a network error or an unreachable server.
- SFTP Authentication: Authentication failed. Please verify your credentials and ensure special characters (like backslashes) are handled correctly.
- SFTP Key Errors: Could not parse or deserialize the private key. Please verify the key format, the algorithm used, and ensure the passphrase is correct.
- URL Access: Access to the provided URL was denied or the server returned an error code.
File & Content Issues
- File Not Found: The specified file or object could not be found at the provided path or URL.
- File Format/Corruption: Could not determine the file type or the file appears to be malformed/corrupted.
- JSON Errors: Could not decode JSON from the file. Please check the file formatting.
- PDF Extraction: Failed to extract text from the PDF. This usually happens with very large or malformed files.
- Empty Content: No text was found in the content stream, or there was no custom vocabulary to upload.
- Import Errors: The system could not determine how to import this specific content.
AWS & S3 Specific Errors
- S3 Connection: Could not connect to the S3 endpoint. Please verify the bucket’s region and your network settings.
- S3 Permissions: Access to the S3 object was denied. Please verify
ListBucketandGetObjectpermissions for the current role. - S3 Missing Objects: No objects were found in the bucket with the specified prefix.
- AWS Bedrock/LLM Errors:
- LLM usage is currently disabled in configuration.
- The request was blocked by a safety guardrail.
- AWS Bedrock is temporarily unavailable or the endpoint URL is invalid.
Data & Configuration Errors
- Duplicate Records: Tried to create a resource using an ID that is already in use within that tenant.
- Missing Resources: The requested resource does not exist.
- CSV Column Mapping: The specified skill column name was not found in the uploaded CSV.
- Tenant State: Attempted to delete data for a tenant that is either unrecognized or currently unlocked.
- Web Crawling Limits: The request exceeded the maximum number of locations allowed to be crawled.
Unexpected Errors
In addition to scenarios that we have explicit error messages for, we also have a generic error format for unexpected errors. For these situations, we generate a unique “error code”, record that code and the details of the exception to the logs, and return the error code in the API response or in the error message of a failed job. This generic error pattern will mention an “internal error” or “internal exception” and include the GUID error code, formatted like “Error code: {guid}”. Your application can consider this situation as something similar to a 500 HTTP status code, and you should refer to the Generator logs for more information.
If you encounter a situation like this with your instance, please feel free to reach out. We are more than happy to look at your logs, identify the issue, recommend next steps, and do what we can to extend our error handling in a future release to provide more specific feedback.