How to fix error: unable to access files outside of sandbox (flatpak) in Git

GitINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 294 views

This error occurs when using Git within a Flatpak application (such as VS Code, GitKraken, or other IDEs) that is restricted by Flatpak's sandbox security model. The fix involves granting the application filesystem permissions to access your project directories using flatpak override, Flatseal, or running with explicit permissions.

Quick fix

Fixes error: unable to access files outside of sandbox (flatpak)

flatpak list --app

Identify the Flatpak application ID
Grant filesystem access using flatpak override
Use Flatseal for graphical permission management
Run the application with temporary permissions

git — error

$flatpak list --app
error: unable to access files outside of sandbox (flatpak)

What this error means

The "unable to access files outside of sandbox" error indicates that a Flatpak-packaged application is attempting to access files or directories that fall outside its permitted sandbox boundaries. Flatpak is a Linux application sandboxing and distribution framework that isolates applications for security purposes. By default, Flatpak applications have extremely limited access to the host filesystem: - **Permitted by default**: The application's own directory, `~/.var/app/$FLATPAK_ID`, and `$XDG_RUNTIME_DIR/app/$FLATPAK_ID` - **Everything else**: Blocked unless explicitly granted When you use Git from within a Flatpak application (like VS Code Flatpak, GitKraken, or other IDEs), the application tries to access your Git repositories, SSH keys, or configuration files. If these locations are not within the sandbox's permitted paths, the operation fails with this error. Common scenarios that trigger this error: - Opening a Git repository located in your home directory from a Flatpak IDE - Running `git clone` to a directory outside the sandbox - Accessing SSH keys in `~/.ssh` for authentication - Reading Git configuration from `~/.gitconfig` - Using Git hooks that reference external scripts

Typical symptoms

Git operations fail with 'unable to access files outside of sandbox'
Cannot open or clone repositories in Flatpak-based IDEs
SSH authentication fails from Flatpak applications
Git status/pull/push commands fail silently or with permission errors
Flatpak IDE cannot find ~/.gitconfig or ~/.ssh/config
Git hooks fail to execute from within Flatpak apps
File picker in Flatpak app cannot navigate to project directories
Terminal inside Flatpak IDE cannot access host system commands

Common causes

Flatpak sandbox restricts filesystem access by default for security
The application was not granted permission to access the required directories
Repository is located outside the app's permitted sandbox paths
SSH keys directory (~/.ssh) is not accessible to the Flatpak app
Git configuration files are in locations blocked by the sandbox
User installed a Flatpak app without realizing the sandbox restrictions
Application manifest does not include necessary filesystem permissions
Override permissions were set system-wide but app is installed per-user (or vice versa)

How to fix "error: unable to access files outside of sandbox (flatpak)"

1Identify the Flatpak application ID

Before granting permissions, you need to find the exact Application ID of the Flatpak app causing the issue.

List all installed Flatpak applications:

bash

flatpak list --app

Filter for a specific app (e.g., VS Code):

bash

flatpak list --app | grep -i code
# Example output: Visual Studio Code   com.visualstudio.code   1.85.0   stable   flathub

Common Flatpak application IDs:
| Application | Flatpak ID |
|-------------|------------|
| VS Code | com.visualstudio.code |
| VS Code - OSS | com.visualstudio.code.oss |
| GitKraken | com.axosoft.GitKraken |
| GNOME Builder | org.gnome.Builder |
| JetBrains IDEs | com.jetbrains.* |

Note the full Application ID (like com.visualstudio.code) as you'll need it for the next steps.

2Grant filesystem access using flatpak override

Use the flatpak override command to permanently grant filesystem access to the application.

Grant access to your home directory:

bash

# For user-installed Flatpak apps (most common)
flatpak override --user --filesystem=home com.visualstudio.code

# For system-wide Flatpak apps (requires sudo)
sudo flatpak override --filesystem=home com.visualstudio.code

Grant access to a specific directory:

bash

# Access to a specific project folder
flatpak override --user --filesystem=/path/to/your/projects com.visualstudio.code

# Access to multiple directories
flatpak override --user --filesystem=~/projects com.visualstudio.code
flatpak override --user --filesystem=~/work com.visualstudio.code

Grant read-only access (more secure):

bash

flatpak override --user --filesystem=~/projects:ro com.visualstudio.code

Grant access to SSH directory for Git authentication:

bash

flatpak override --user --filesystem=~/.ssh:ro com.visualstudio.code
flatpak override --user --filesystem=~/.gitconfig:ro com.visualstudio.code

Important: After setting overrides, restart the Flatpak application for changes to take effect.

3Use Flatseal for graphical permission management

Flatseal is a graphical utility that makes managing Flatpak permissions much easier than command-line tools.

Install Flatseal:

bash

flatpak install flathub com.github.tchx84.Flatseal

Use Flatseal to grant permissions:
1. Launch Flatseal: flatpak run com.github.tchx84.Flatseal
2. Select the problematic application from the left sidebar
3. Scroll down to the "Filesystem" section
4. Toggle on "All user files" for full home directory access, OR
5. Click "Other files" and add specific paths like:
- ~/projects
- ~/.ssh (for Git SSH authentication)
- ~/.gitconfig (for Git configuration)
6. Close Flatseal and restart the application

Benefits of Flatseal:
- Visual overview of all permissions
- Easy to see what access an app already has
- Reset button to restore default permissions
- No need to remember command-line syntax

4Run the application with temporary permissions

If you want to grant permissions temporarily without making permanent changes, use the flatpak run command with permission flags.

Run with filesystem access:

bash

# Run VS Code with home directory access
flatpak run --filesystem=home com.visualstudio.code

# Run with specific directory access
flatpak run --filesystem=/path/to/project com.visualstudio.code

# Run with multiple permissions
flatpak run --filesystem=home --filesystem=~/.ssh:ro com.visualstudio.code

Create a shell alias for convenience:

bash

# Add to ~/.bashrc or ~/.zshrc
alias code='flatpak run --filesystem=home com.visualstudio.code'

Run with full host access (not recommended for security):

bash

flatpak run --filesystem=host com.visualstudio.code

This method is useful for:
- Testing if permission is the issue
- One-time access without permanent changes
- Running with different permission sets

5Configure SSH and Git access for Flatpak

Git operations often require access to SSH keys and Git configuration files. Here's how to set up proper access:

Grant SSH directory access:

bash

# Read-only access to SSH keys (recommended)
flatpak override --user --filesystem=~/.ssh:ro com.visualstudio.code

# Also grant access to SSH agent socket
flatpak override --user --socket=ssh-auth com.visualstudio.code

Grant Git configuration access:

bash

# Access to global Git config
flatpak override --user --filesystem=~/.gitconfig:ro com.visualstudio.code

# If using XDG config directory
flatpak override --user --filesystem=~/.config/git:ro com.visualstudio.code

Use host Git commands via flatpak-spawn:
Some Flatpak apps support running host commands. In VS Code, you can configure the integrated terminal to use the host shell:

json

// settings.json
{
  "terminal.integrated.profiles.linux": {
    "host-bash": {
      "path": "/usr/bin/flatpak-spawn",
      "args": ["--host", "--env=TERM=xterm-256color", "bash"]
    }
  },
  "terminal.integrated.defaultProfile.linux": "host-bash"
}

This allows the terminal to run Git from the host system, bypassing sandbox restrictions.

6Verify and troubleshoot permissions

After making changes, verify that permissions are correctly applied.

Check current overrides for an app:

bash

flatpak override --show com.visualstudio.code

# Check user-level overrides
flatpak override --user --show com.visualstudio.code

View the app's declared permissions:

bash

flatpak info --show-permissions com.visualstudio.code

Reset all overrides to defaults:

bash

# Reset user overrides
flatpak override --user --reset com.visualstudio.code

# Reset system overrides (requires sudo)
sudo flatpak override --reset com.visualstudio.code

Test file access from within the Flatpak:

bash

# Enter the Flatpak sandbox
flatpak run --command=bash com.visualstudio.code

# Check if you can access your files
ls ~/projects
cat ~/.gitconfig
ls ~/.ssh

Common troubleshooting steps:
1. Ensure you're using --user flag for user-installed apps
2. Restart the application after changing permissions
3. Check for typos in the Application ID (case-sensitive)
4. Verify the path exists and is spelled correctly

7Consider alternatives to Flatpak installation

If Flatpak's sandbox restrictions are too limiting for your development workflow, consider alternative installation methods.

Use native packages instead:

bash

# VS Code from Microsoft repository (Debian/Ubuntu)
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg
sudo install -o root -g root -m 644 packages.microsoft.gpg /etc/apt/trusted.gpg.d/
sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/code stable main" > /etc/apt/sources.list.d/vscode.list'
sudo apt update
sudo apt install code

# Or use snap (less sandboxed in classic mode)
sudo snap install code --classic

Use AppImage versions:
Many applications offer AppImage downloads that run without sandboxing:
1. Download the .AppImage file
2. Make it executable: chmod +x ./Application.AppImage
3. Run directly: ./Application.AppImage

Keep Flatpak for non-development apps:
You can have both installations:
- Use Flatpak for general applications (browsers, media players)
- Use native packages for development tools that need full system access

Remove the Flatpak version:

bash

flatpak uninstall com.visualstudio.code
# Also remove unused runtimes
flatpak uninstall --unused

Advanced notes

Understanding Flatpak's Security Model:

Flatpak uses Linux kernel features like namespaces, seccomp, and cgroups to create an isolated environment. This is fundamentally different from traditional package managers - Flatpak apps run in a container-like sandbox.

Reserved/Blacklisted Paths:

Even with --filesystem=host, certain paths cannot be accessed:
- /lib, /lib32, /lib64
- /bin, /sbin, /usr
- /boot, /root, /tmp
- /etc, /proc, /sys, /dev
- /app, /run, /var

These restrictions exist to prevent apps from tampering with the host system.

Using Portals for Better Security:

Modern Flatpak apps should use XDG Portals instead of direct filesystem access:
- File chooser portal lets users select files without granting blanket access
- Document portal provides access only to explicitly chosen files
- This is the recommended pattern for new applications

bash

# Check if an app uses portals
flatpak info --show-permissions com.example.app | grep -i portal

Override Files Location:

Flatpak stores override configurations in:
- User overrides: ~/.local/share/flatpak/overrides/
- System overrides: /var/lib/flatpak/overrides/

You can manually edit these files (JSON format) or delete them to reset permissions.

Debugging Permission Issues:

Run an app with verbose logging:

bash

FLATPAK_DEBUG=1 flatpak run com.visualstudio.code

Use strace to trace system calls (requires permissions):

bash

flatpak run --devel --command=strace com.visualstudio.code -f -e openat your_command

Bubblewrap and bwrap-info:

Flatpak uses Bubblewrap (bwrap) for sandboxing. You can inspect the sandbox:

bash

flatpak run --command=cat com.visualstudio.code /proc/self/mountinfo

Security Considerations:

- Granting --filesystem=home gives access to sensitive files like .ssh, .gnupg, browser profiles
- Prefer granting access to specific directories when possible
- Use :ro suffix for read-only access when write access isn't needed
- Regularly audit permissions with Flatseal
- Be cautious with --filesystem=host as it bypasses most sandbox protections

Frequently asked questions

What does "error: unable to access files outside of sandbox (flatpak)" mean?: The "unable to access files outside of sandbox" error indicates that a Flatpak-packaged application is attempting to access files or directories that fall outside its permitted sandbox boundaries. Flatpak is a Linux application sandboxing and distribution framework that isolates applications for security purposes. var/app/$FLATPAK_ID, and $XDG_RUNTIME_DIR/app/$FLATPAK_ID - Everything else: Blocked unless explicitly granted When you use Git from within a Flatpak application (like VS Code Flatpak, GitKraken, or other IDEs), the application tries to access your Git repositories, SSH keys, or configuration files.
How do I fix "error: unable to access files outside of sandbox (flatpak)"?: This error occurs when using Git within a Flatpak application (such as VS Code, GitKraken, or other IDEs) that is restricted by Flatpak's sandbox security model. The fix involves granting the application filesystem permissions to access your project directories using flatpak override, Flatseal, or running with explicit permissions.
What causes "error: unable to access files outside of sandbox (flatpak)"?: Flatpak sandbox restricts filesystem access by default for security The application was not granted permission to access the required directories Repository is located outside the app's permitted sandbox paths
Is the "error: unable to access files outside of sandbox (flatpak)" error serious?: It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading

📚Git Official Documentation
📖
Sandbox Permissions - Flatpak Documentation(Official Docs)
📖
Basic Concepts - Flatpak Documentation(Official Docs)
🔗
Flatseal - Graphical Flatpak Permissions Manager
💬
How to give a Flatpak app access to a directory - Ask Ubuntu(Stack Overflow)
💬
How to always run a flatpak application with a filesystem permission - Unix Stack Exchange(Stack Overflow)
🐙
Git integration: ssh_askpass not found - VS Code Flatpak Issues(GitHub)

How to fix error: unable to access files outside of sandbox (flatpak) in Git

Quick fix

What this error means

Typical symptoms

Common causes

How to fix "error: unable to access files outside of sandbox (flatpak)"

Advanced notes

Frequently asked questions

Related errors

Official resources & further reading