Troubleshooting

Relevant source files

The following files were used as context for generating this wiki page:

• tauri.conf.json
• package.json
• src-tauri/src/lib.rs
• src/App.jsx
• vite.config.js
• src/Hooks/useListStore.js
• src/components/Form/Form.jsx
• src/components/DetailView/DetailView.jsx
• src-tauri/capabilities/default.json

This document provides guidance for diagnosing and resolving common issues encountered during the development, building, and operation of the Scripty application. It covers problems related to the development environment, backend Rust services, frontend React components, data persistence, and the auto-updater mechanism. The application is built using Tauri, React, and Vite, and understanding the interaction between these technologies is key to effective troubleshooting.

Build and Development Environment

Issues in this area typically stem from misconfigurations in the Vite development server, Tauri build commands, or dependency mismatches.

Key Configuration Files

File	Purpose
package.json	Defines Node.js dependencies (react, vite, @tauri-apps/api) and scripts (dev, build, tauri).
vite.config.js	Configures the Vite development server, including port, HMR (Hot Module Replacement), and build-specific options.
tauri.conf.json	Configures the Tauri application, including build commands, window properties, plugins, and the auto-updater.
src-tauri/Cargo.toml	Defines Rust dependencies (crates) for the Tauri backend, such as tauri, serde, and various Tauri plugins.

Sources: package.json, vite.config.js, src-tauri/tauri.conf.json, src-tauri/Cargo.toml

Common Problems

1. Port Conflict: The Vite server may fail to start if the configured port is in use.

   • Symptom: Error message in the console indicating "port 1420 is already in use".
   • Solution: The vite.config.js is set to strictPort: true, which will cause Vite to exit if the port is unavailable. Ensure no other processes are using port 1420.
   • Sources: vite.config.js:20-21

2. Rust Errors Obscured: Vite might hide compilation errors from the Rust backend.

   • Symptom: The frontend loads, but backend calls fail silently or the app crashes without clear Rust error logs.
   • Solution: The vite.config.js sets clearScreen: false to prevent Vite from clearing the console, ensuring Rust errors are visible.
   • Sources: vite.config.js:17

3. Incorrect Build Commands: The Tauri build process relies on commands specified in tauri.conf.json.

   • Symptom: tauri build fails with an error related to npm run build.
   • Solution: Verify that the beforeBuildCommand (npm run build) and beforeDevCommand (npm run dev) are correctly defined and that the corresponding scripts exist in package.json.
   • Sources: src-tauri/tauri.conf.json:8,10, package.json:6,8

The diagram below illustrates the development startup flow.

Sources: src-tauri/tauri.conf.json:8, package.json:6, vite.config.js:20

Backend (Rust/Tauri) Issues

The backend is responsible for interacting with the operating system, primarily by executing PowerShell commands.

Tauri Commands

The lib.rs file exposes several functions to the frontend via the Tauri invoke mechanism.

Command	Parameters	Description
open_terminal	content: String	Spawns a new PowerShell instance and executes the provided command string. Runs as the current user.
open_admin_terminal	content: String	Spawns a new PowerShell instance with administrator privileges to execute the command.
run_sys_terminal	content: String	Extracts an embedded syspwsh.exe and uses it to run a command as the SYSTEM user.
read_ps1	path: String	Reads the content of a .ps1 file from the specified path and returns it to the frontend.

Sources: src-tauri/src/lib.rs:29-62

Common Problems

1. "Failed to start elevated PowerShell":

   • Symptom: The open_admin_terminal command fails. This typically happens if the User Account Control (UAC) prompt is denied or if there's a policy preventing elevation.
   • Solution: Ensure the user accepts the UAC prompt. Check system security policies. The command constructs a Start-Process call with the -Verb RunAs argument.
   • Sources: src-tauri/src/lib.rs:36-46

2. "Failed to resolve the .ps1 file":

   • Symptom: When adding a new script, the application shows an error dialog.
   • Solution: This error is returned by the read_ps1 Rust command when fs::read_to_string fails. This indicates the file path provided by the frontend's open-file dialog is invalid or the file is unreadable. The frontend displays a "File nicht gefunden" message.
   • Sources: src-tauri/src/lib.rs:60-63, src/components/Form/Form.jsx:24-27

3. syspwsh.exe Extraction Fails:

   • Symptom: The run_sys_terminal command fails.
   • Solution: This command relies on extracting an embedded executable to the user's temporary directory (env::temp_dir()). This can fail due to lack of permissions to write to the temp directory. The function checks if the file exists before writing.
   • Sources: src-tauri/src/lib.rs:11-20

The following diagram shows the sequence of a frontend component invoking a backend command.

Sources: src/components/DetailView/DetailView.jsx:21-23, src-tauri/src/lib.rs:36-46

Data Persistence

Script data (items and tags) is managed by Zustand and persisted to a JSON file on the local disk using @tauri-apps/plugin-fs.

Storage Mechanism

• State Management: useListStore (a Zustand store) holds the items and tags in memory.
• Persistence: The persist middleware from Zustand is used to save the state.
• Storage Location: A custom storage object is implemented that uses readTextFile and writeTextFile from the Tauri FS plugin. The data is saved to scriptStorage.json inside the application's data directory (appDataDir).

Sources: src/Hooks/useListStore.js:1-50

The following code snippet defines the custom file storage interface for Zustand.

// src/Hooks/useListStore.js:13-27
const fileStorage = {
  getItem: async (_) => {
    const path = await getFileStorePath();
    if (!(await exists(path))) return null;
    return await readTextFile(path);
  },
  setItem: async (_, value) => {
    const path = await getFileStorePath();
    await writeTextFile(path, value);
  },
  removeItem: async (_) => {
    const path = await getFileStorePath();
    await writeTextFile(path, "");
  },
};

Common Problems

1. Scripts not saving between sessions:

   • Symptom: Added scripts are gone after restarting the application.
   • Solution: This indicates a problem with the setItem function in fileStorage. Check the application's permissions. The default.json capability file must grant appropriate fs permissions, such as fs:allow-appdata-write and fs:allow-write-text-file. Also, check for errors in the developer console related to file system access.
   • Sources: src/Hooks/useListStore.js:20-23, src-tauri/capabilities/default.json:17, 68

2. Corrupted scriptStorage.json:

   • Symptom: The application fails to load, crashes on start, or displays no scripts.
   • Solution: The getItem function reads the file content. If the JSON is malformed, JSON.parse (used internally by Zustand's middleware) will fail. Manually locate the scriptStorage.json file in the path returned by appDataDir and either fix the JSON structure or delete it to let the application create a new one.
   • Sources: src/Hooks/useListStore.js:14-18

Auto-Updater

The application includes an auto-updater configured via tauri.conf.json and invoked in App.jsx.

Configuration and Flow

• Enabled: The updater is activated in tauri.conf.json.
• Public Key: A pubkey is required to verify the signature of the update manifest.
• Endpoint: The updater checks for a latest.json file at the specified URL.

// src-tauri/tauri.conf.json:49-56
"updater": {
  "active": true,
  "pubkey": "dW50cnVzdGVkIGNvbW1lbnQ6IG1pbmlzaWduIHB1YmxpYyBrZXk6IDQxRURENUVBNzg3NzAzMzUKUldRMUEzZDQ2dFh0UVl3VGRodXNtRmNWV2VFUkZpWWo0TWpnZXVMZ05XLzhYb0hkU1hPUng5NEYK",
  "endpoints": [
    "https://github.com/SemtexHR/ScriptTool/releases/latest/download/latest.json%22
  ]
}

The update check is performed on application startup.

// src/App.jsx:14-15
const update = await check();
if (update) {
  // ... download and install logic
}

Common Problems

1. Update Check Fails:

   • Symptom: The app never prompts for an update, even when a new version is available.
   • Solution:
     1. Verify the endpoints URL in tauri.conf.json is correct and reachable.
     2. Ensure the pubkey matches the key used to sign the update artifacts.
     3. Check the developer console for network errors or errors from the @tauri-apps/plugin-updater.
   • Sources: src-tauri/tauri.conf.json:49-56, src/App.jsx:14

2. Download Fails or Gets Stuck:

   • Symptom: The update is found, but the download progress hangs or fails.
   • Solution: The downloadAndInstall callback provides progress events. Use console.log within this callback to debug the download progress (Started, Progress, Finished). This can help identify if the download starts at all or where it stops. Network issues or firewalls could be blocking the download.
   • Sources: src/App.jsx:21-34