Skip to main content
This guide covers common issues you might encounter when using Open Screen and how to resolve them.
Open Screen is currently in beta. If you encounter issues not covered here, please report them on the GitHub Issues page.

​
Installation Issues

​
macOS: App is Blocked by Gatekeeper

Symptom: macOS shows “Openscreen cannot be opened because it is from an unidentified developer” Solution: Bypass Gatekeeper using the terminal command: 
xattr -rd com.apple.quarantine /Applications/Openscreen.app
  1. Open Terminal (Applications > Utilities > Terminal)
  2. Ensure Terminal has Full Disk Access:
    • Open System Settings > Privacy & Security > Full Disk Access
    • Enable the toggle for Terminal
  3. Copy and paste the command above, then press Enter
  4. Navigate to System Settings > Privacy & Security
  5. Grant Screen Recording and Accessibility permissions to Openscreen
  6. Launch the app from Applications
You must grant Terminal Full Disk Access before running the command, otherwise it will silently fail.

​
Linux: AppImage Won’t Launch

Symptom: Double-clicking the AppImage does nothing, or shows a permissions error Solution 1: Make the AppImage executable: 
chmod +x Openscreen-Linux-*.AppImage
./Openscreen-Linux-*.AppImage
Solution 2: If you see a sandbox error, run with --no-sandbox: 
./Openscreen-Linux-*.AppImage --no-sandbox
The --no-sandbox flag is required on some Linux distributions where Electron’s sandbox is incompatible with the system configuration.

​
Windows: Installation Blocked by SmartScreen

Symptom: Windows Defender SmartScreen prevents installation Solution: Click “More info” and then “Run anyway”
Only do this for downloads from the official GitHub releases page. Never run unverified executables.

​
Recording Issues

​
No Recording Source Available

Symptom: Can’t start recording, or “Please select a source to record” alert appears Solution:
  1. Ensure you’ve granted screen recording permissions
  2. Select a source before clicking Record:
    • Click the source selector dropdown
    • Choose either your entire screen or a specific application
  3. Try restarting the app after granting permissions
macOS:
  • System Settings > Privacy & Security > Screen Recording
  • Enable toggle for Openscreen
Linux (GNOME/Wayland):
  • You may be prompted for permission when first recording
  • Click “Allow” in the permission dialog
Windows:
  • Screen recording is usually allowed by default
  • If blocked, check Windows Privacy settings

​
Recording Starts But Immediately Stops

Symptom: Recording indicator appears briefly, then stops without saving Possible causes and solutions:
  1. Insufficient disk space
    • Check that you have at least 1GB free space
    • Recordings can use 100-500MB per minute depending on resolution
  2. Permission denied after starting
    • On macOS: Recheck Screen Recording permissions
    • Try restarting the app after granting permissions
  3. Codec not supported
    • The app should automatically fall back to a supported codec
    • Check the console logs for codec selection messages

​
Low Recording Quality

Symptom: Recording appears lower resolution than expected Solution: Open Screen automatically records at the highest quality your system supports, up to 4K at 60 FPS. However, actual quality depends on:
  1. Your display resolution - Can’t record higher than native resolution
  2. System capabilities - GPU and CPU performance affect achievable quality
  3. Selected source - Some application windows may have resolution limits
Check the console output when starting a recording. It will show the actual resolution, frame rate, codec, and bitrate being used.

​
Recording Not Saved

Symptom: Recording completes but video file is not available Solution:
  1. Check the recordings directory for the video file
  2. Ensure the app has write permissions to the recordings folder
  3. Look for error messages in the developer console (View > Developer > Developer Tools)
  4. Verify you have sufficient disk space

​
Playback and Editing Issues

​
Video Won’t Play in Editor

Symptom: Recording loads but won’t play, or shows a black screen Possible solutions:
  1. Codec compatibility issue
    • Try re-recording with a different source
    • Check that the video file isn’t corrupted
  2. GPU/WebGL issue
    • Ensure your GPU supports WebGL 2.0
    • Try updating your graphics drivers
    • Restart the application
  3. File corruption
    • If recording was interrupted, the file may be corrupted
    • Try recording a short test video to verify the app is working

​
Timeline Becomes Unresponsive

Symptom: Can’t add effects, timeline doesn’t respond to clicks Solutions:
  1. Pause playback before editing
  2. Close and reopen the project
  3. Reduce the number of effects (zoom, annotations, etc.)
  4. Ensure sufficient RAM is available (close other applications)

​
Zoom/Effects Not Appearing

Symptom: Added zoom regions or effects don’t show in preview Solution:
  1. Ensure the effect is within the video timeline (not in trimmed sections)
  2. Check that the playhead is positioned within the effect’s duration
  3. Try adjusting the effect’s timing or position
  4. Verify the effect wasn’t accidentally deleted
Effects in trimmed sections will not appear in the final export, even if visible in the timeline.

​
Export Issues

​
Export Fails or Gets Stuck

Symptom: Export starts but fails partway through, or progress bar stops advancing Common causes and solutions:
  1. Insufficient disk space
    • Ensure you have at least 2GB free space for exports
    • Large/long videos require more space
  2. Encoder error
    • Check developer console for error messages
    • Try a lower quality setting (Medium instead of Source)
    • Try a different export format (MP4 vs GIF)
  3. Memory exhaustion
    • Close other applications to free up RAM
    • For GIF exports, use a smaller size preset or lower frame rate
    • Try exporting a shorter section first
  4. Complex effects
    • Very complex projects with many effects may struggle to export
    • Try removing some effects temporarily
    • Export in segments and combine externally if needed
If export fails during the “Compiling GIF” phase, this usually indicates insufficient memory. Try reducing GIF size preset or frame rate.

​
Export Takes Too Long

Symptom: Export is working but extremely slow Optimization tips:
  1. For MP4 exports:
    • Check if hardware acceleration is being used (shown in logs)
    • Update your GPU drivers to enable hardware encoding
    • Use “Good” or “Medium” quality instead of “Source”
    • Close other GPU-intensive applications
  2. For GIF exports:
    • Reduce frame rate (15 or 20 FPS instead of 30)
    • Use “Medium” size preset instead of “Large” or “Original”
    • Consider exporting as MP4 instead for better quality and speed
    • GIF compilation is CPU-intensive and can take several minutes
GIF exports are inherently slower than MP4. A 30-second video at 30 FPS can take 5-10 minutes to compile. This is normal.

​
Exported Video Has Wrong Aspect Ratio

Symptom: Video appears stretched or has black bars Solution:
  1. Double-check the aspect ratio setting before exporting
  2. Ensure the aspect ratio matches your intended platform (16:9 for YouTube, 9:16 for Stories, etc.)
  3. If using custom crop, verify the crop region is set correctly
  4. Re-export with the correct aspect ratio selected

​
Exported Video Quality Is Poor

Symptom: Export looks pixelated or blurry compared to preview Solutions:
  1. Use “Source” or “Good” quality instead of “Medium”
  2. Ensure your source recording was high quality
  3. For GIF exports:
    • Use higher frame rate (25-30 FPS)
    • Use “Large” or “Original” size preset
    • Note: GIFs have inherent quality limitations due to 256-color palette
  4. Avoid excessive zooming or scaling

​
Performance Issues

​
App Feels Slow or Laggy

Symptom: UI is unresponsive, preview stutters Solutions:
  1. Close other applications to free up RAM and CPU
  2. Reduce preview quality by resizing the window
  3. Disable motion blur in settings (if enabled)
  4. Simplify your project:
    • Reduce number of annotations
    • Minimize overlapping effects
    • Use fewer keyframes
  5. Update graphics drivers for better GPU performance
  6. Restart the application to clear memory

​
High CPU/GPU Usage

Symptom: Fans running loud, system gets hot This is normal during:
  • Active recording (encoding video in real-time)
  • Video playback with effects (rendering in real-time)
  • Exporting (encoding final video)
To reduce load:
  • Pause playback when not needed
  • Use lower quality settings for previewing
  • Export during idle time
  • Ensure good ventilation for your computer

​
Graphics and Rendering Issues

​
WebGL Errors

Symptom: “WebGL not supported” or rendering errors Solutions:
  1. Update your graphics drivers
  2. Ensure your GPU supports WebGL 2.0 (most GPUs from 2012+)
  3. Try disabling hardware acceleration in your OS settings, then re-enabling
  4. Check if other GPU-intensive apps work (to rule out hardware issues)

​
Motion Blur Causes Artifacts

Symptom: Visual glitches when motion blur is enabled Solutions:
  1. Disable motion blur in settings
  2. Reduce motion blur intensity
  3. This may be a GPU compatibility issue - try updating drivers

​
Annotations Disappear or Glitch

Symptom: Added text/arrows/images don’t render correctly Solutions:
  1. Ensure the annotation is within the video duration
  2. Check that the annotation isn’t hidden behind other elements
  3. Try adjusting the Z-order (layer order) of annotations
  4. Remove and re-add the annotation
  5. Restart the app if the issue persists

​
macOS-Specific Issues

​
Permissions Keep Getting Reset

Symptom: Need to re-grant Screen Recording permission repeatedly Solutions:
  1. After running the xattr command, fully restart your Mac
  2. Ensure the app isn’t installed in a restricted location
  3. Try moving the app to /Applications if it’s elsewhere
  4. Check for macOS security software that might be blocking permissions

​
App Crashes on Apple Silicon

Symptom: App crashes or won’t launch on M1/M2/M3 Macs Solutions:
  1. Ensure you downloaded the correct version (Apple Silicon vs Intel)
  2. Try the Rosetta version if the native version doesn’t work
  3. Update to the latest version of macOS
  4. Check Console.app for crash logs and report the issue on GitHub

​
Linux-Specific Issues

​
Wayland Compositor Issues

Symptom: Screen recording doesn’t work on Wayland Solutions:
  1. Grant portal permissions when prompted
  2. Try switching to X11 session temporarily
  3. Ensure xdg-desktop-portal is installed and running
  4. Check your desktop environment’s screen recording support

​
Missing System Dependencies

Symptom: AppImage won’t run due to missing libraries Solution: Install required dependencies for your distribution: 
# Ubuntu/Debian
sudo apt install libfuse2

# Fedora
sudo dnf install fuse-libs

# Arch
sudo pacman -S fuse2

​
Getting Help

GitHub Issues

Report bugs and request features

Discussions

Ask questions and share tips

​
Before Reporting an Issue

Please include:
  1. Your platform and version (macOS 14.2, Windows 11, Ubuntu 22.04, etc.)
  2. Open Screen version (check in About dialog)
  3. Steps to reproduce the issue
  4. Expected vs actual behavior
  5. Console logs if available (View > Developer > Developer Tools > Console)
  6. Screenshots or screen recordings of the issue
Open Screen is actively maintained. Most reported issues are addressed quickly. Check existing issues before creating a new one.

​
Known Limitations

These are current limitations that may be addressed in future versions:
  • No audio recording support (video only)
  • No multi-track timeline
  • No built-in undo/redo (use file > revert)
  • GIF exports can be very large for long videos
  • No real-time preview of all effects during playback (performance optimization)
  • Maximum 4K export resolution
Check the project roadmap to see what features are planned.

Build docs developers (and LLMs) love

Get started for freeTalk to us