tauri-apps/tauri · error

failed to canonicalize global API script path

Error message

failed to canonicalize global API script path

What it means

tauri_utils::plugin::define_global_api_script_path is called from a plugin's build.rs to register a global API script; it canonicalizes the given path (resolve to absolute, follow symlinks) and prints it as a cargo: directive. Path::canonicalize fails when the target file does not exist or an intermediate directory cannot be traversed.

Source

Thrown at crates/tauri-utils/src/plugin.rs:27

#[cfg(any(feature = "build", feature = "build-2"))]
mod build {
  use std::{
    env::vars_os,
    fs,
    path::{Path, PathBuf},
  };

  const GLOBAL_API_SCRIPT_PATH_KEY: &str = "GLOBAL_API_SCRIPT_PATH";
  /// Known file name of the file that contains an array with the path of all API scripts defined with [`define_global_api_script_path`].
  pub const GLOBAL_API_SCRIPT_FILE_LIST_PATH: &str = "__global-api-script.js";

  /// Defines the path to the global API script using Cargo instructions.
  pub fn define_global_api_script_path(path: &Path) {
    println!(
      "cargo:{GLOBAL_API_SCRIPT_PATH_KEY}={}",
      path
        .canonicalize()
        .expect("failed to canonicalize global API script path")
        .display()
    )
  }

  /// Collects the path of all the global API scripts defined with [`define_global_api_script_path`]
  /// and saves them to the out dir with filename [`GLOBAL_API_SCRIPT_FILE_LIST_PATH`].
  ///
  /// `tauri_global_scripts` is only used in Tauri's monorepo for the examples to work
  /// since they don't have a build script to run `tauri-build` and pull in the deps env vars
  pub fn save_global_api_scripts_paths(out_dir: &Path, mut tauri_global_scripts: Option<PathBuf>) {
    let mut scripts = Vec::new();

    for (key, value) in vars_os() {
      let key = key.to_string_lossy();

      if key == format!("DEP_TAURI_{GLOBAL_API_SCRIPT_PATH_KEY}") {
        tauri_global_scripts = Some(PathBuf::from(value));
      } else if key.starts_with("DEP_") && key.ends_with(GLOBAL_API_SCRIPT_PATH_KEY) {

View on GitHub (pinned to 52e4b6e71d)

Solutions

1. Ensure the script file exists before the call: commit it or generate it earlier in build.rs.
2. Anchor the path: Path::new(&env::var("CARGO_MANIFEST_DIR").unwrap()).join("api.js").
3. Log path.display() before the call to see what is actually resolved and fix typos.

Example fix

// before
define_global_api_script_path(Path::new("./generated/api.js")); // not generated yet

// after
let api = Path::new(&std::env::var("CARGO_MANIFEST_DIR").unwrap()).join("api.js");
assert!(api.is_file(), "missing {}", api.display());
define_global_api_script_path(&api);

// in the plugin build.rs, before registering
if !path.is_file() {
    panic!("global API script not found at {} - generate or commit it first", path.display());
}
tauri_utils::plugin::define_global_api_script_path(&path);

When it happens

Trigger: Calling define_global_api_script_path with a path to a file that does not exist yet (e.g. generated after build.rs runs), a typo, or a relative path resolved against an unexpected working directory (build scripts run in the package root).

Common situations: Plugin build script referencing a JS file that is generated later or not committed; relative paths not anchored to CARGO_MANIFEST_DIR.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• failed to write global API script
• Tauri "Isolation" Pattern only supports relative or absolute
• failed to read plugin global API script paths
• failed to write checked_features file
• Failed to write kotlin file

AI-assisted analysis of tauri-apps/tauri@52e4b6e71d (2026-08-20). Data as JSON: /api/errors/8d651e79d483f3b6. Report an issue: GitHub.