Tauri v2 Upgrade Guide: Solving Permission Denied & ACL Errors

 

The Upgrade Pain: "Command not found"

You have migrated your tauri.conf.json to v2 format, updated your Cargo dependencies, and the application builds. But the moment your frontend attempts to interact with the system—reading a file, opening a dialog, or persisting store data—the console throws a rejection:

IPC Connection Error: Command not found or Permission Denied.

In Tauri v1, security was managed via a straightforward allowlist in tauri.conf.json. You toggled fs: { all: true }, and your app had access. In Tauri v2, this entire section is deprecated and non-functional. The allowlist has been replaced by an Access Control List (ACL) system based on Capabilities. If you do not explicitly define a capability set and map it to your application window, your frontend is effectively sandboxed from the Rust backend.

Root Cause: The Shift from Config to Capabilities

Tauri v2 decouples core features into standalone plugins (e.g., @tauri-apps/plugin-fs, @tauri-apps/plugin-os). This modularity reduces binary size but breaks the old monolithic permission model.

The error occurs because the IPC bridge now strictly enforces Capability Files. When the frontend invokes a command, Tauri's backend checks:

1. Is the plugin registered in Rust?
2. Does a JSON/TOML file in src-tauri/capabilities/ exist?
3. Does that file target the current window label (e.g., "main")?
4. Does that file explicitly list the permission identifier for the requested command?

If any of these are missing, the IPC call is rejected before it ever reaches your Rust logic.

The Fix: Implementing v2 ACLs

We will implement a complete fix using the File System (fs) plugin as the example. This process applies identically to shell, dialog, http, and other core plugins.

1. Install the v2 Plugin Dependencies

You must install the plugin in both the Rust backend and the JavaScript frontend.

Terminal:

# Rust Backend
cargo add tauri-plugin-fs

# Frontend (npm/pnpm/yarn)
npm install @tauri-apps/plugin-fs

2. Register the Plugin in Rust

Update your entry point (usually src-tauri/src/lib.rs for v2 templates, or main.rs) to initialize the plugin.

src-tauri/src/lib.rs

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        // Initialize the FS plugin here
        .plugin(tauri_plugin_fs::init())
        .setup(|app| {
            if cfg!(debug_assertions) {
                app.handle().plugin(
                    tauri_plugin_log::Builder::default()
                        .level(log::LevelFilter::Info)
                        .build(),
                )?;
            }
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

3. Define the Capability (The Critical Step)

Create a new directory src-tauri/capabilities if it doesn't exist. Create a file named default.json inside it. This replaces the old allowlist.

src-tauri/capabilities/default.json

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default-capability",
  "description": "Capability for the main window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "fs:default",
    "fs:allow-read-text-file",
    "fs:allow-write-text-file",
    "fs:allow-mkdir"
  ]
}

Note: If your application uses multiple windows with different labels, add them to the windows array.

4. Scope the Permissions (Optional but Recommended)

In v2, permissions can be scoped to specific directories for tighter security. If fs:default is too permissive, you can define specific scopes in tauri.conf.json or within the capability file itself.

Here is how to restrict file access to the $APP_DATA directory strictly within the capability file:

src-tauri/capabilities/restricted-fs.json

{
  "identifier": "fs-scope",
  "windows": ["main"],
  "permissions": [
    {
      "identifier": "fs:scope",
      "allow": [{ "path": "$APP_DATA/**" }]
    },
    "fs:allow-read-text-file",
    "fs:allow-write-text-file"
  ]
}

5. Frontend Implementation

Do not use window.__TAURI__ or generic invokes. Import the specific plugin methods.

src/components/FileHandler.tsx

import { useState } from 'react';
import { BaseDirectory, readTextFile, writeTextFile } from '@tauri-apps/plugin-fs';

export default function FileHandler() {
  const [content, setContent] = useState<string>('');
  const [status, setStatus] = useState<string>('Idle');

  const handleSave = async () => {
    try {
      setStatus('Saving...');
      // Writes to $APP_DATA/example.txt
      await writeTextFile('example.txt', 'Hello from Tauri v2 ACLs!', {
        baseDir: BaseDirectory.AppData,
      });
      setStatus('Saved successfully');
    } catch (error) {
      console.error(error);
      setStatus(`Error: ${error}`);
    }
  };

  const handleRead = async () => {
    try {
      setStatus('Reading...');
      const text = await readTextFile('example.txt', {
        baseDir: BaseDirectory.AppData,
      });
      setContent(text);
      setStatus('Read complete');
    } catch (error) {
      console.error(error);
      setStatus(`Error: ${error}`);
    }
  };

  return (
    <div className="p-4 border rounded bg-gray-900 text-white">
      <h2 className="text-xl font-bold mb-4">FS Plugin Test</h2>
      <div className="flex gap-2 mb-4">
        <button 
          onClick={handleSave}
          className="px-4 py-2 bg-blue-600 hover:bg-blue-700 rounded transition"
        >
          Write File
        </button>
        <button 
          onClick={handleRead}
          className="px-4 py-2 bg-green-600 hover:bg-green-700 rounded transition"
        >
          Read File
        </button>
      </div>
      <div className="bg-gray-800 p-2 rounded font-mono text-sm">
        <p>Status: {status}</p>
        <p>Content: {content}</p>
      </div>
    </div>
  );
}

Why This Works

1. Plugin Registration: The main.rs change registers the plugin's Rust logic. Without this, the frontend invoke command targets a namespace that doesn't exist in the backend.
2. Capability Mapping: When the frontend calls writeTextFile, the Tauri IPC layer inspects the default.json capability.
3. Window Validation: It confirms the request originated from the main window (as defined in windows: ["main"]).
4. Permission Validation: It verifies that fs:allow-write-text-file is present in the permissions list.
5. Scope Validation: It ensures the requested path resolves to BaseDirectory.AppData (if scoping is active).

This multi-layer verification is significantly more secure than v1 because it prevents a compromised third-party webview or a secondary window from executing high-privilege system commands unless explicitly authorized.

Conclusion

The "Command not found" error in Tauri v2 is almost always a missing Capability file or an unregistered plugin. While the new ACL system requires more boilerplate than the v1 allowlist, it provides the granular security controls necessary for professional desktop applications. Create your src-tauri/capabilities/default.json, map your permissions, and your IPC layer will function correctly.