Troubleshooting

​

Authentication

​

”Invalid API key” Error

1. Verify the API key is correct (check for typos or extra whitespace)
2. Ensure the key hasn’t been deleted or revoked
3. Check that you’re using the correct header format: X-Avala-Api-Key
4. Confirm you’re sending the key as a header, not a query parameter

# Verify your API key works
curl -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  https://server.avala.ai/api/v1/datasets/

​

”API key has expired” Error

1. Create a new API key in Mission Control under Settings
2. Update your applications and environment variables with the new key
3. Consider setting longer or no expiration for production keys
4. Set up key rotation alerts to avoid unexpected expirations

​

”Permission denied” Error

1. Verify you have access to the requested dataset or project
2. Check your organization membership and role (admin, manager, annotator)
3. Ensure your API key has the required scopes for the operation
4. Contact your organization admin to request access

​

API Issues

​

Rate Limiting (429 Too Many Requests)

1. Implement exponential backoff in your retry logic
2. Check the Retry-After header for the recommended wait time
3. Reduce the number of concurrent requests
4. For bulk operations, use batch endpoints where available

import time

def handle_rate_limit(response):
    if response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 5))
        print(f"Rate limited. Waiting {retry_after} seconds...")
        time.sleep(retry_after)
        return True
    return False

​

Pagination Errors

1. Use cursor-based pagination instead of offset pagination
2. Do not modify filters between pagination requests
3. Pass the full next URL returned by the API rather than constructing it manually
4. Check that the next field is null to detect the last page

​

Request Timeout

1. Increase your client timeout setting (recommended: 30 seconds for standard requests)
2. For large exports or uploads, use a longer timeout (60-120 seconds)
3. Check your network connection and firewall settings
4. If specific endpoints consistently time out, contact support

​

Uploads

​

Upload Fails for Large Files

1. Check your network connection stability
2. Use the SDK’s built-in upload methods, which handle chunked uploads automatically
3. For files over 1 GB, ensure your client timeout is set to at least 120 seconds
4. Try uploading during off-peak hours
5. For very large datasets, consider splitting into smaller batches

​

”Invalid file format” Error

1. Verify the file is a supported format:
   • Images: JPEG, PNG, WebP
   • Videos: MP4, MOV
   • Point clouds: PCD, PLY
   • Sensor data: MCAP, ROS Bag
2. Check that the file is not corrupted
3. Ensure file extension matches actual content type

​

MCAP Parsing Errors

1. Validate your MCAP file locally using the MCAP CLI
2. Ensure all schemas referenced by channels exist in the file
3. Check that timestamps are monotonically increasing within each channel
4. Verify the file was not truncated during transfer

​

Datasets

​

Items Not Appearing

1. Check if processing is still in progress (look for the processing status indicator)
2. Refresh the page or re-fetch via the API
3. Verify the upload completed successfully by checking the upload response status
4. Check that items match the dataset’s expected data type

​

”Dataset not found” Error

1. Verify you’re using the correct owner and slug format:
   Copy

   Ask AI

   # Format: /datasets/{owner}/{slug}/
   curl "https://server.avala.ai/api/v1/datasets/acme-ai/my-dataset/" \
     -H "X-Avala-Api-Key: $AVALA_API_KEY"
   
2. Check dataset visibility (private datasets require explicit access)
3. Confirm you have permission to view the dataset
4. Ensure the dataset has not been deleted

​

Sequence Status Stuck

1. Wait up to 15 minutes for large sequences to finish processing
2. Check that all referenced files in the sequence were uploaded successfully
3. Verify the sequence data is in a supported format
4. If stuck for more than 30 minutes, contact support with the sequence ID

​

Projects

​

Can’t Create Project

1. Ensure you have at least one dataset selected as the data source
2. Verify you have permission to create projects in the organization (manager or admin role)
3. Check that your label taxonomy is valid and does not contain duplicate label names
4. Ensure the project name is unique within your organization

​

Annotations Not Saving

1. Check your network connection for intermittent issues
2. Verify you have edit permissions on the project
3. Look for error messages in the browser console (F12)
4. Ensure the task has not been reassigned or completed by another user
5. Try refreshing the page and re-annotating

​

Task Assignment Issues

1. Verify annotators have been added to the project with the correct role
2. Check that the work batch configuration is correct
3. Ensure there are unassigned tasks available in the project
4. Confirm the project status is active (paused projects do not assign new tasks)

​

Exports

​

Export Stuck in “Processing”

1. Check that the project has completed annotations to export
2. Try creating a smaller export by filtering by date or task status
3. For large exports (10,000+ items), allow up to 30 minutes for processing
4. Contact support if stuck for more than 1 hour

​

”Download URL expired” Error

1. Export download URLs expire after 7 days
2. Create a new export to generate a fresh download URL
3. Automate the download step in your pipeline to avoid expiration

​

Empty Export

1. Verify the project has completed and accepted tasks
2. Check that your export filters are not too restrictive
3. Ensure annotations exist for the selected export format
4. Try exporting without filters to confirm data exists

​

Mission Control

​

Viewer Not Loading

1. Check the browser console for errors (F12 on most browsers)
2. Try a different browser (Chrome or Firefox recommended)
3. Clear browser cache and reload the page
4. Verify the dataset item has completed processing
5. Disable browser extensions that may interfere (ad blockers, privacy tools)

​

Slow Performance

1. Close other browser tabs to free memory
2. Use a modern browser with hardware acceleration enabled
3. For large point clouds, reduce point density in the viewer settings
4. Check your internet connection speed (minimum 10 Mbps recommended)
5. Try zooming into a smaller area of the dataset

​

3D Viewer Issues

1. Ensure your browser supports WebGL 2.0
2. Update your GPU drivers to the latest version
3. Enable hardware acceleration in your browser settings
4. Reduce the point cloud density if rendering is slow
5. Try a different browser if rendering artifacts appear

​

MCP Integration

​

MCP Endpoint Not Responding

1. Verify you are sending requests to POST /api/v1/mcp/ with a valid API key
2. Ensure your API key has staff-level access (the MCP endpoint is currently staff-only)
3. Check that the request body is valid JSON-RPC format
4. Review the response body for specific error details

​

MCP Authentication Errors

1. Verify your AVALA_API_KEY environment variable is set correctly
2. Ensure the API key has not expired or been revoked
3. Confirm the API key has staff-level permissions (required for the MCP endpoint)
4. Check that you are including the key in the X-Avala-Api-Key header

​

Getting Help

1. Search our documentation at docs.avala.ai
2. Email support at support@avala.ai with details about the issue, including any error messages and steps to reproduce
3. Visit our GitHub repository for SDK issues, bug reports, and feature requests