Troubleshooting

Troubleshooting

Common issues and solutions for DosKit.

Common Issues

"DOS emulator library not loaded"

Problem: js-dos failed to load from CDN.

Solutions:

1. Check your internet connection
2. Verify CDN is accessible: https://v8.js-dos.com/latest/js-dos.js
3. Check browser console for CORS or network errors
4. Try refreshing the page
5. Clear browser cache

Black Screen / Emulator Not Starting

Problem: Emulator loads but shows black screen.

Solutions:

1. Check browser console for errors
2. Verify WebAssembly is supported: typeof WebAssembly !== 'undefined'
3. Try a different browser
4. Disable browser extensions that might interfere
5. Check if hardware acceleration is enabled

Poor Performance / Lag

Problem: Emulator runs slowly.

Solutions:

1. Reduce CPU cycles in DOSBox config: cycles=10000
2. Enable hardware acceleration in browser settings
3. Close other browser tabs
4. Try a different rendering backend: renderBackend: 'canvas'
5. Reduce screen resolution if possible

Keyboard Not Working

Problem: Keyboard input not registering.

Solutions:

1. Click inside the emulator window to focus it
2. Check if browser has focus (not in another tab)
3. Try clicking the "Play" button if visible
4. On mobile, use the on-screen keyboard
5. Check browser console for errors

Audio Not Playing

Problem: No sound from DOS applications.

Solutions:

1. Audio is automatically unmuted when the emulator is ready
2. Check browser audio is not muted (system volume and browser tab)
3. Verify volume setting: volume: 0.7 in options
4. Click inside emulator to ensure user interaction (required by browsers)
5. Check if DOS application has sound enabled in its settings
6. Verify DOSBox sound card configuration (Sound Blaster, GUS, etc.)
7. Check browser console for audio-related errors

Note: Modern browsers require user interaction before audio can play.

Mobile Touch Controls Not Appearing

Problem: On-screen keyboard missing on mobile.

Solutions:

1. Verify you're on a mobile device (check user agent)
2. Check mobile configuration is applied
3. Try portrait and landscape orientations
4. Refresh the page
5. Check softKeyboardLayout in config

Service Worker Not Updating

Problem: App not updating to latest version.

Solutions:

1. Click "Update Available" notification when it appears
2. Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
3. Clear browser cache and reload
4. Unregister service worker in DevTools > Application > Service Workers
5. Close all tabs and reopen

Files Not Loading / Network Errors

Problem: DOS application files fail to download.

Solutions:

1. Check internet connection
2. Verify GitHub/CDN is accessible
3. Check browser console for CORS errors
4. Try again later (may be rate limited)
5. Check if using VPN or proxy that might block requests

High Memory Usage

Problem: Browser using too much memory.

Solutions:

1. Close other browser tabs
2. Reduce DOSBox memory: memsize=16 in config
3. Clear browser cache
4. Restart browser
5. Use a 64-bit browser if available

Debug Mode

Enable detailed logging in development:

// Logs are automatically enabled in development mode
// Check browser console for detailed information
// Use logger utility for custom logging:
import { logger } from "./utils/logger";
logger.debug("Debug message");

Performance Tips

• Reduce CPU cycles for better battery life on mobile
• Enable hardware acceleration in browser settings
• Use cache-first mode for offline performance
• Close unused tabs to free up memory
• Disable browser extensions that might interfere

Getting Help

If you encounter issues not covered here:

1. Check the browser console for error messages
2. Review js-dos documentation: https://js-dos.com
3. Check existing issues: https://github.com/cameronrye/doskit/issues
4. Open a new issue: Include browser version, OS, and console errors
5. Read Architecture: For technical details

Include in your issue:

• Browser and version
• Operating system
• Error messages from console
• Steps to reproduce

---

Made with ❤️ by Cameron Rye