Troubleshooting Guide

This guide provides systematic approaches to diagnosing and resolving common issues with Dropstone.io. Follow these steps to gather the necessary information before reaching out to support.

Essential Information for Troubleshooting

The following information is critical for most troubleshooting scenarios within Dropstone:

1. Visual Documentation

Screenshot of Issue (redact any sensitive information)

• Capture the entire application window showing the error
• Include any error messages or dialogs
• Ensure timestamps are visible if available

2. Reproduction Steps

Provide detailed steps to reproduce the issue:

1. Action taken (e.g., "Clicked on 'Deploy' button")
2. Expected behavior
3. Actual behavior
4. Frequency (always, sometimes, once)

3. System Information

Retrieve system information from:

Dropstone → Help → About

This includes:

• Dropstone version
• Operating system
• Architecture (x64, arm64)
• Electron version
• Node.js version

4. Network Configuration

Are you using any of the following?

• VPN (Virtual Private Network)
• Zscaler or other security proxies
• Corporate firewall
• Custom DNS settings

5. Developer Tools Console

Access developer tools to check for JavaScript errors:

Dropstone → Help → Toggle Developer Tools

Navigate to the Console tab and check for:

• Red error messages
• Warning messages related to your issue
• Network request failures

Copy any relevant error stack traces.

6. Application Logs

Windows

Logs are located at:

C:\Users\<your-username>\AppData\Roaming\Dropstone\logs

Access via Command Palette:

1. Press Ctrl + Shift + P
2. Type and select: Developer: Open Logs Folder

macOS

Logs are located at:

~/Library/Application Support/Dropstone/logs

Access via Command Palette:

1. Press Cmd + Shift + P
2. Type and select: Developer: Open Logs Folder

Linux

Logs are located at:

~/.config/Dropstone/logs

Viewing Logs in Application

Navigate to: Dropstone → Terminal → Output

Select from the dropdown:

• Window - General application logs
• Dropstone Core - Core functionality logs
• Dropstone Deployment - Deployment-related logs
• Dropstone Storage - Storage and database logs
• Dropstone API - API request/response logs

Common Issues and Solutions

Connection Issues

Problem: Unable to Connect to Dropstone Services

Symptoms:

• "Connection timeout" errors
• "Unable to reach server" messages
• Indefinite loading states

Solutions:

1. Check Internet Connection

   # Windows
   ping dropstone.io
   
   # macOS/Linux
   ping dropstone.io
   

2. Verify Firewall Settings

   • Ensure Dropstone is allowed through your firewall
   • Check corporate network policies
   • Whitelist *.dropstone.io domain

3. Proxy Configuration

   Configure proxy settings:

   Dropstone → Settings → Network → Proxy Settings

   Or set environment variables:

   export HTTP_PROXY=http://proxy.example.com:8080
   export HTTPS_PROXY=http://proxy.example.com:8080
   

4. DNS Resolution

   • Flush DNS cache
   • Try alternative DNS (8.8.8.8, 1.1.1.1)

Authentication Issues

Problem: Login Failures or Token Expiration

Symptoms:

• "Authentication failed" errors
• Repeated login prompts
• 401 Unauthorized responses

Solutions:

1. Clear Authentication Cache

   Dropstone → Command Palette → Clear Authentication Cache

2. Re-authenticate

   1. Sign out from Dropstone
   2. Clear browser cookies for dropstone.io
   3. Sign in again
   

3. Check Token Validity

   Navigate to: Settings → Account → Session Management

   Review active sessions and revoke suspicious ones.

4. SSO Issues

   If using Single Sign-On:

   • Verify SSO provider is accessible
   • Check for expired SAML assertions
   • Contact your identity provider administrator

Performance Issues

Problem: Slow Application Response or High CPU Usage

Symptoms:

• Lag when typing or clicking
• High CPU/memory usage
• Frozen or unresponsive UI

Solutions:

1. Check Resource Usage

   Dropstone → Help → Process Manager

   Identify processes consuming excessive resources.

2. Disable Extensions

   Temporarily disable extensions to isolate the issue:

   Settings → Extensions → Disable all → Restart

3. Clear Cache

   Dropstone → Settings → Advanced → Clear Cache
   

4. Reduce Project Size

   • Exclude large files from indexing
   • Add to .dpsignore file:
   node_modules/
   dist/
   build/
   *.log
   .git/
   

5. Hardware Acceleration

   Toggle GPU acceleration:

   Settings → System → Use Hardware Acceleration

Deployment Issues

Problem: Failed Deployments

Symptoms:

• Build failures
• Deployment timeouts
• "Unable to push to remote" errors

Solutions:

1. Check Build Logs

   View detailed build output:

   Deployment → History → Select failed deployment → View Logs

2. Verify Environment Variables

   Settings → Deployment → Environment Variables
   

   Ensure all required variables are set.

3. Check Deployment Configuration

   Validate your dropstone.config.js:

   module.exports = {
     build: {
       command: 'npm run build',
       output: 'dist'
     },
     deployment: {
       region: 'us-east-1',
       runtime: 'nodejs18.x'
     }
   }
   

4. Storage Quota

   Verify you haven't exceeded storage limits:

   Dashboard → Usage → Storage

5. Build Timeout

   Increase timeout in configuration:

   deployment: {
     timeout: 900 // 15 minutes in seconds
   }
   

Storage and Database Issues

Problem: Data Sync or Storage Errors

Symptoms:

• "Storage quota exceeded"
• Sync conflicts
• Data not persisting

Solutions:

1. Check Storage Usage

   Dashboard → Storage → Usage Statistics

2. Resolve Sync Conflicts

   1. Navigate to conflicted file
   2. Dropstone will show conflict markers
   3. Resolve manually or select version to keep
   

3. Database Connection

   Test database connectivity:

   // In Dropstone console
   await dropstone.db.test()
   

4. Clear Local Cache

   Settings → Storage → Clear Local Cache
   

   Warning: This will remove locally cached data.

5. Backup and Restore

   Create backup before troubleshooting:

   Dropstone → Tools → Backup → Create Backup
   

Advanced Troubleshooting

Safe Mode

Start Dropstone in safe mode to disable all extensions:

Windows/Linux:

dropstone --disable-extensions

macOS:

/Applications/Dropstone.app/Contents/MacOS/Dropstone --disable-extensions

Reset to Default Settings

To reset all settings to defaults:

1. Backup Current Settings

   Settings → Advanced → Export Settings
   

2. Reset

   Settings → Advanced → Reset All Settings
   

Verbose Logging

Enable detailed logging for debugging:

1. Open Command Palette (Ctrl/Cmd + Shift + P)
2. Select: Developer: Set Log Level
3. Choose: Trace

Logs will now include detailed diagnostic information.

Network Diagnostics

Run built-in network diagnostics:

Dropstone → Help → Run Network Diagnostics

This checks:

• DNS resolution
• API endpoint accessibility
• WebSocket connections
• CDN availability

Getting Help

Before Contacting Support

Ensure you have:

• Checked this troubleshooting guide
• Searched Community Forum
• Reviewed Status Page
• Gathered all essential troubleshooting information

Contact Support

Email: support@dropstone.io

Include in your message:

1. Issue summary
2. Steps to reproduce
3. System information
4. Relevant logs (last 100 lines)
5. Screenshots
6. What you've already tried

Response Time:

• Critical (production down): 1 hour
• High priority: 4 hours
• Normal: 24 hours
• Low priority: 48 hours

Community Resources

• Documentation: docs.dropstone.io
• Community Forum: community.dropstone.io
• GitHub Issues: github.com/dropstone/dropstone
• Discord: discord.gg/dropstone
• Status Page: status.dropstone.io

Useful Commands

Command Palette Quick Reference

CLI Diagnostics

# Check Dropstone CLI version
dropstone --version

# Verify installation
dropstone doctor

# Test API connectivity
dropstone ping

# View current configuration
dropstone config list

# Clear local cache
dropstone cache clear

# Export logs
dropstone logs export --output ./dropstone-logs.txt

Appendix

Log File Locations

Configuration File Locations

Environment Variables

Last Updated: September 29, 2025 Version: 1.0.0