Troubleshooting

Solutions to common issues when using Avala.

Authentication

”Invalid API key” Error

Problem: API requests return 401 Unauthorized with “Invalid API key” message.

Solutions:

1. Verify the API key is correct (check for typos or extra whitespace)
2. Ensure the key hasn’t been deleted or expired
3. Check that you’re using the correct header format

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

”API key has expired” Error

Problem: API returns 401 Unauthorized with expired key message.

Solutions:

1. Create a new API key in Mission Control → Settings → API Keys
2. Update your applications with the new key
3. Consider setting longer or no expiration for production keys

”Permission denied” Error

Problem: API returns 403 Forbidden when accessing a resource.

Solutions:

1. Verify you have access to the requested dataset/project
2. Check your organization membership and role
3. Contact your organization admin for access

Uploads

Upload Fails for Large Files

Problem: Uploads timeout or fail for large files.

Solutions:

1. Check your network connection stability
2. Try uploading during off-peak hours
3. For very large datasets, consider splitting into smaller batches

”Invalid file format” Error

Problem: Upload rejected with format error.

Solutions:

1. Verify the file is a supported format:
   • Images: JPEG, PNG, WebP
   • Videos: MP4, MOV
   • Point clouds: PCD, PLY, MCAP
2. Check file isn’t corrupted
3. Ensure file extension matches content

Datasets

Items Not Appearing

Problem: Uploaded items don’t show in the dataset.

Solutions:

1. Check if processing is still in progress (look for spinner)
2. Refresh the page
3. Verify the upload completed successfully (no errors)

“Dataset not found” Error

Problem: Can’t access a dataset that should exist.

Solutions:

1. Verify you’re using the correct owner/slug:

   # Format: /datasets/{owner}/{slug}/
   curl "https://api.avala.ai/api/v1/datasets/johndoe/my-dataset/" \
     -H "X-Avala-Api-Key: $AVALA_API_KEY"

2. Check dataset visibility (private datasets require access)
3. Verify you have permission to view the dataset

Projects

Can’t Create Project

Problem: Project creation fails.

Solutions:

1. Ensure you have a dataset selected
2. Verify you have permission to create projects in the organization
3. Check that your label taxonomy is valid

Annotations Not Saving

Problem: Annotations disappear after saving.

Solutions:

1. Check your network connection
2. Verify you have edit permissions on the project
3. Look for error messages in the console
4. Try refreshing and re-annotating

Exports

Export Stuck in “Processing”

Problem: Export never completes.

Solutions:

1. Check if the project has completed annotations to export
2. Try creating a smaller export (filter by date or status)
3. Contact support if stuck for more than 30 minutes

”Download URL expired” Error

Problem: Can’t download a completed export.

Solutions:

1. Export download URLs expire after 7 days
2. Create a new export
3. Download immediately after completion for time-sensitive needs

Mission Control

Viewer Not Loading

Problem: Annotation viewer shows blank or loading spinner.

Solutions:

1. Check browser console for errors (F12 → Console)
2. Try a different browser (Chrome recommended)
3. Clear browser cache and reload
4. Verify the dataset item has completed processing

Slow Performance

Problem: Interface is slow or unresponsive.

Solutions:

1. Close other browser tabs
2. Use a modern browser with hardware acceleration
3. For large point clouds, try reducing point density in settings
4. Check your internet connection speed

Getting Help

If you’re still stuck:

1. Check our documentation at docs.avala.ai
2. Email support at support@avala.ai