Skip to main content

​
Mount issues

​
Mount fails with “FUSE not found”

FUSE is required for filesystem mounting. 
brew install macfuse
# Restart your computer after installation

​
Mount point is not empty

The mount directory must be empty: 
# Check if directory has files
ls ~/airstore

# If empty but mount fails, try unmounting first
airstore unmount ~/airstore

# Or use system unmount
fusermount -u ~/airstore  # Linux
diskutil unmount ~/airstore  # macOS

​
Permission denied on mount

Linux: Add yourself to the fuse group: 
sudo usermod -aG fuse $USER
# Log out and back in
macOS: macFUSE may need security approval:
  1. Open System Preferences → Security & Privacy
  2. Click “Allow” for the macFUSE kernel extension
  3. Restart your computer

​
Mount hangs or times out

Check if the Airstore service is reachable: 
airstore status --verbose
If using self-hosted, verify the gateway is running: 
curl http://your-gateway:8080/health

​
OAuth issues

​
OAuth fails with “redirect_uri mismatch”

The OAuth app’s redirect URI doesn’t match. For self-hosted:
  1. Check your OAuth app configuration in the provider’s developer console
  2. Ensure the redirect URI matches your config.yaml:
oauth:
  gmail:
    redirect_uri: https://your-domain.com/oauth/gmail/callback

​
OAuth window closes without completing

  • Disable popup blockers for the Airstore domain
  • Try a different browser
  • Check browser console for errors

​
Token expired

Re-authenticate the source: 
airstore connect gmail --reauth

​
Sync issues

​
Files not updating

Smart folders sync periodically in the background. To force immediate sync: 
airstore sync sources/gmail/my-folder
Check sync status: 
airstore status sources/gmail/my-folder

​
Sync is slow

Large queries take longer to materialize. Try:
  1. Make queries more specific
  2. Reduce the date range
  3. Check source API rate limits
# Instead of
airstore create sources/gmail/all --query "all emails"

# Use
airstore create sources/gmail/recent --query "emails from the last 7 days"

​
”Query could not be translated” error

The natural language query couldn’t be converted to the source’s API format. Try:
  • Being more specific
  • Using terms the source API supports
  • Checking the source documentation for supported filters
# Too vague
airstore create sources/gmail/important --query "important stuff"

# Better
airstore create sources/gmail/important --query "emails marked important"

​
Tool issues

​
Tool not found

Verify the tool exists: 
ls ~/airstore/tools/
If missing, check if the source is connected: 
airstore sources list

​
Tool returns error

Check the error message: 
~/airstore/tools/github create-issue --repo=acme/api --title="Test" 2>&1
Common causes:
  • Missing required arguments
  • Invalid argument values
  • API rate limits
  • Insufficient permissions

​
Tool is disabled

Check tool status: 
airstore tools list
Enable if needed: 
airstore tools enable github

​
MCP server issues

​
Custom MCP server won’t start

Test the command directly: 
npx @company/mcp-server
Check for:
  • Missing dependencies
  • Invalid environment variables
  • Port conflicts

​
MCP server crashes

View server logs: 
airstore logs my-server --verbose
Test the server: 
airstore mcp test my-server --verbose

​
Performance issues

​
Reads are slow

Reads should be fast (cached). If slow:
  1. Check if initial sync is complete: 
    airstore status sources/gmail/my-folder
  2. Verify network connectivity to the gateway
  3. For self-hosted, check gateway resources (CPU, memory)

​
High memory usage

Large smart folders consume more memory. Solutions:
  • Create more specific queries
  • Split large folders into smaller ones
  • Increase gateway memory (self-hosted)

​
Authentication issues

​
”Not authenticated” error

Log in again: 
airstore login

​
Token invalid for cloud mount

Generate a new token: 
airstore token create --name="new-token"
Update your cloud environment with the new token.

​
Getting help

If you’re still stuck:
  1. Check logs: 
    airstore logs --verbose
  2. Run diagnostics: 
    airstore doctor
  3. File an issue: github.com/beam-cloud/airstore/issues

​
Next steps

FAQ

Frequently asked questions.

Self-hosting

Run your own instance.