Troubleshooting

Desktop IDE Issues

App won’t launch

xattr -cr /Applications/Atlas\ Studio.app

# Check crash logs
open ~/Library/Logs/DiagnosticReports
# Or check Atlas Studio logs
cat ~/Library/Logs/Atlas\ Studio/main.log

%APPDATA%\Atlas Studio\logs\main.log

# Check FUSE is installed
fusermount --version || sudo apt install libfuse2
 
# Check execute permission
chmod +x AtlasStudio.AppImage
 
# Run with debug output
APPIMAGE_DEBUG=1 ./AtlasStudio.AppImage

# Run without sandbox (for testing only)
./AtlasStudio.AppImage --no-sandbox

License activation fails

“License key not recognized”

• Ensure you copy the full key including the ATLAS-STUDIO-FREE- prefix
• Check for extra spaces (copy-paste issue)
• Verify the email matches the one used at signup
• Try via Web Portal first: studio.atlastechlab.com/login 

“Could not reach license server”

• Check internet connectivity
• If behind a proxy: Settings → Network → configure proxy
• Verify atlasaiop.com:443 is reachable: curl -I https://atlasaiop.com/api/health
• Check your firewall — see required endpoints in Installation

“License already active on another machine”

• Sign in to Web Portal → Settings → License → Active Devices → deactivate the old machine
• Then re-activate on the new machine

AI agents not responding

“AI model error: rate limit exceeded”

• You’ve hit your monthly credit limit — check Web Portal → Billing → Usage
• Upgrade your plan or wait for the monthly reset
• For Coding Agent: switch to BYOM (your own API key)

“AI model error: invalid API key”

• BYOM key is wrong or expired — Settings → AI → BYOM → re-enter key
• Ensure the key has usage enabled in your provider’s dashboard

Agent runs but produces poor results

• Switch to a higher model tier (Deep Reasoning for RCA, Balanced for workflows)
• Provide more context in your prompt (incident ID, service name, time range)
• Ensure relevant connectors are connected and healthy

Connector issues

“Connector test failed: connection refused”

• Check the connector host/port is reachable from your machine
• For Kubernetes: ensure kubectl works independently (kubectl get pods)
• For Datadog: verify the API key in Datadog → Organization Settings → API Keys

“Authentication failed”

• Token/password may have expired — regenerate in the source system
• Check permissions: the Atlas connector user needs read access to metrics/logs

Kubernetes: “unable to connect to server”

• Check kubeconfig: kubectl config current-context
• Atlas Studio uses the current kubeconfig by default — Settings → Connectors → Kubernetes → specify kubeconfig path if non-default

Workflow issues

“Workflow failed: permission denied on runner”

• The runner doesn’t have permission to execute on the target
• Check runner credentials: Web Portal → Settings → Credentials → verify the credential used by this workflow
• For SSH targets: ensure the runner’s public key is in ~/.ssh/authorized_keys on the target

“Workflow stuck in RUNNING state”

• Go to Web Portal → Workflows → Executions → find the stuck run → Force Terminate
• Check runner health: Web Portal → Runners → ensure the runner is online

“Node failed: command not found”

• The command isn’t in the runner’s PATH
• Add /usr/local/bin or other paths to the runner environment: Web Portal → Runners → Environment Variables

Performance issues

IDE is slow or freezing

• Check memory usage: macOS Activity Monitor / Windows Task Manager
• Increase available memory by closing other apps
• Reduce the number of open connectors (disconnect unused ones)
• Clear the local cache: Settings → Advanced → Clear Cache

Large workflows load slowly

• Workflows with > 50 nodes may be slow to render — expected behavior in v1.0
• Use sub-workflows to break large orchestrations into smaller pieces

Web Portal Issues

Can’t log in

“Invalid email or password”

• Use the Forgot Password  flow
• Check if you signed up with a different email

“Account locked”

• Too many failed login attempts — wait 15 minutes or contact support

Redirected to marketing site instead of portal

• Ensure you’re going to studio.atlastechlab.com (not atlastechlab.com/studio)

Workflows not running on schedule

Check runner health Web Portal → Runners → ensure at least one runner is Online and assigned to the workflow.

Check timezone Cron expressions are evaluated in the timezone configured for the workflow. Web Portal → Workflows → Edit → Scheduling → Timezone.

Check business calendar If the workflow uses a business calendar, today may be a non-business day.

Log Locations

Getting support logs

To send logs to Atlas support:

1. Atlas Studio → Help → Collect Diagnostics
2. This creates a zip file with: main.log, renderer.log, crash-reports, system info
3. Email to support@atlastechlab.com with your account email and a description of the issue

Common Error Codes

Resetting the Local Database

# macOS
rm -rf ~/Library/Application\ Support/Atlas\ Studio/data/
 
# Windows (PowerShell)
Remove-Item "$env:APPDATA\Atlas Studio\data\" -Recurse -Force
 
# Linux
rm -rf ~/.local/share/Atlas\ Studio/data/

Then relaunch Atlas Studio — it will reinitialize the database and prompt you to sign in again.

Getting Help

• Documentation: docs.atlastechlab.com/atlas-studio 
• Email support: support@atlastechlab.com
• Response time: 24 hours for Growth/Pro, 4 hours for Enterprise
• Community: community.atlastechlab.com