Troubleshooting Guide

Having issues with The Stratus? This guide covers common problems and their solutions. If you can't find what you're looking for, check the FAQ or contact support.

Installation Issues

Extension Not Showing Up

Problem: The Stratus extension doesn't appear after installation.

Solutions:

1. Reload VS Code: Cmd+Shift+P → Developer: Reload Window
2. Check if extension is enabled: Extensions → Search "Stratus" → Click "Enable"
3. Verify installation: Extensions → "Installed" tab
4. Try reinstalling the extension

Command Not Found

Problem: "Stratus: Configure" or other commands don't appear in Command Palette.

Solutions:

1. Ensure extension is activated (check status bar)
2. Open a workspace/folder (Stratus requires a workspace)
3. Reload VS Code window
4. Check extension host: Cmd+Shift+P → Developer: Show Running Extensions

Connection Issues

Failed to Connect to AWS S3

Error: Access Denied or Invalid Credentials

Solutions:

1. Verify access key ID and secret access key are correct
2. Check IAM user has s3:PutObject and s3:GetObject permissions
3. Ensure bucket exists and is in the specified region
4. Check bucket policy allows access from your IAM user
5. Verify region is correct (e.g., us-east-1)

// Test connection command
Cmd+Shift+P → "Stratus: Test Connection"

SFTP Connection Timeout

Error: Connection timeout or ECONNREFUSED

Solutions:

1. Verify host and port are correct (default SFTP port is 22)
2. Check firewall isn't blocking connection
3. Ensure SSH service is running on remote server
4. Try SSH connection manually: ssh user@host
5. Check VPN connection if required

SSL/TLS Certificate Errors

Error: Certificate verification failed

Solutions:

1. Update to latest version of The Stratus
2. Check system date/time is correct
3. For self-signed certificates, add to configuration:

   "config": {
     "rejectUnauthorized": false
   }

Sync Issues

Files Not Syncing

Problem: Files aren't being uploaded when saved.

Solutions:

1. Check auto-sync is enabled: Stratus: Enable Auto-Sync
2. Verify file isn't in ignorePatterns
3. Check status bar shows "Stratus: Active"
4. Review Output panel for errors: Stratus: Show Output
5. Try manual sync: Stratus: Sync Now

Only Some Files Sync

Problem: Some files upload but others don't.

Solutions:

1. Check watchPatterns in configuration
2. Review ignorePatterns - they might be too broad
3. Ensure file paths don't exceed provider limits
4. Check file size isn't exceeding limits

// Example: Only sync dist folder
"watchPatterns": ["dist/**/*"]

Sync is Very Slow

Problem: File uploads take a long time.

Solutions:

1. Increase parallel uploads (Pro users):

   "parallelUploads": 10

2. Use MD5 comparison to avoid re-uploading unchanged files:

   "compareBy": "md5"

3. Check network connection speed
4. Choose cloud region closer to your location
5. Exclude unnecessary files with ignorePatterns

Configuration Issues

Invalid Configuration Error

Error: Failed to parse configuration

Solutions:

1. Validate JSON syntax using a JSON validator
2. Check for missing commas or quotes
3. Ensure required fields are present:
   • version
   • activeProfile
   • profiles object
4. Use configuration wizard: Stratus: Configure

Profile Not Found

Error: Profile 'production' not found

Solutions:

1. Verify profile name in activeProfile matches a profile in profiles
2. Check spelling (case-sensitive)
3. Create profile: Stratus: Add New Server

Permission Errors

AWS S3 Access Denied

Error: Access Denied when uploading

Solutions:

1. Check IAM policy grants necessary permissions:

   {
     "Version": "2012-10-17",
     "Statement": [{
       "Effect": "Allow",
       "Action": [
         "s3:PutObject",
         "s3:GetObject",
         "s3:DeleteObject",
         "s3:ListBucket"
       ],
       "Resource": [
         "arn:aws:s3:::my-bucket/*",
         "arn:aws:s3:::my-bucket"
       ]
     }]
   }

2. Verify bucket policy allows access
3. Check bucket isn't using Block Public Access (if needed)

SFTP Permission Denied

Error: Permission denied when writing files

Solutions:

1. Check user has write permissions on target directory
2. Verify directory path is correct
3. Check file ownership and permissions on server
4. Try creating directory manually via SSH

Performance Issues

High CPU Usage

Problem: VS Code becomes slow when syncing

Solutions:

1. Reduce parallel uploads:

   "parallelUploads": 2

2. Use more specific watchPatterns
3. Increase ignorePatterns to exclude large folders
4. Disable auto-sync for large projects:

   "uploadOnSave": false

Extension Crashes

Problem: Extension stops working or crashes VS Code

Solutions:

1. Check extension logs: Help → Toggle Developer Tools → Console
2. Disable other conflicting extensions
3. Update to latest version of The Stratus
4. Update VS Code to latest version
5. Email support with logs at support@thestratus.co

Diagnostic Commands

Use these commands to diagnose issues:

Still Need Help?

If you can't find a solution here:

1. Check FAQ: Frequently Asked Questions
2. Review Documentation: Getting Started Guide
3. Email Support: support@thestratus.co