How to Recover from Invalid TOML Configuration Files in OpenLogi

OpenLogi implements a defensive configuration loader that detects malformed TOML syntax and schema mismatches, automatically falling back to default values while preserving the corrupted file in a versioned backup.

The AprilNEA/OpenLogi repository manages user preferences through a single config.toml file located in the application's configuration directory. When you need to recover from invalid TOML configuration files in OpenLogi, the system provides multiple safeguards—from automatic error handling at startup to manual cleanup procedures—that prevent application crashes and data loss.

How OpenLogi Detects Configuration Errors

Parse Error Classification in ConfigFile::load_from_path

When the application starts, ConfigFile::load_from_path (defined in crates/openlogi-core/src/config/file.rs at line 250) attempts to deserialize the TOML file using toml::from_str. The implementation distinguishes between three specific failure modes through the ConfigError enum:

• ConfigError::Parse – Triggered when the TOML parser encounters syntax errors, missing brackets, or malformed values
• ConfigError::ObsoleteField – Raised when the configuration contains deprecated keys no longer supported by the current schema
• ConfigError::UnsupportedSchemaVersion – Occurs when the schema_version declared in the file exceeds the application's supported range

Graceful Degradation via load_or_default

Rather than propagating errors that would crash the application, OpenLogi uses ConfigFile::load_or_default (line 118 in crates/openlogi-core/src/config/file.rs) as the primary entry point. This function returns a tuple containing the configuration object and an optional error, enabling the following recovery behavior:

• On successful load: Returns the parsed configuration with no error
• On parse failure: Returns a fresh default configuration alongside the specific ConfigError
• In the desktop application: The caller at crates/openlogi-desktop/src/main.rs (line 78) logs a warning such as "could not load config.toml; disabling config writes" before continuing execution with in-memory defaults

Automatic Backup Creation with backup_config_once

Before the system overwrites any existing file, the loader invokes backup_config_once at line 199 in crates/openlogi-core/src/config/file.rs. This function creates a timestamped backup (e.g., config.toml.v4.bak) ensuring the original corrupted content remains accessible for forensic analysis or manual data recovery.

Manual Recovery Steps for Corrupted Configurations

If automatic recovery produces unexpected defaults or you need to repair the file manually, follow this procedure:

1. Inspect the configuration file – Open ~/.config/openlogi/config.toml (location determined by crates/openlogi-core/src/paths.rs) in a text editor to identify syntax errors such as unclosed strings or misplaced commas.

2. Archive the corrupted file – Rename the broken configuration using mv config.toml config.toml.broken to prevent the loader from attempting to parse invalid syntax on the next startup.

3. Restart OpenLogi – Launch the application to trigger generation of a fresh config.toml containing factory defaults, which the system writes based on the reference schema in docs/config.example.toml.

4. Migrate valid settings – Copy non-corrupted sections from your archived backup into the newly generated file, ensuring all fields comply with the current schema version to avoid triggering ConfigError::ObsoleteField or ConfigError::UnsupportedSchemaVersion errors.

Implementing Programmatic Recovery

For custom tooling or automated deployment scenarios, OpenLogi exposes its internal recovery logic through the public API:

use openlogi_core::config::{ConfigFile, ConfigError};

fn recover_config() -> Result<(), ConfigError> {
    // Attempt to load the user’s config; on error fall back to defaults.
    let (config, err) = ConfigFile::load_or_default()?;
    if let ConfigError::Parse { .. } = err {
        // Log the parse error; the returned `config` is the default.
        eprintln!("Config parse failed – using defaults: {err}");
    }
    // Persist the (possibly refreshed) config back to disk.
    ConfigFile::default().save(&config)?;
    Ok(())
}

This pattern mirrors the implementation in the desktop client: it attempts to load user preferences, logs parse failures while continuing with defaults, and writes a clean configuration file to disk.

Key Source Files and Implementation Details

Understanding these core files enables advanced troubleshooting and custom builds:

• crates/openlogi-core/src/config/file.rs – Contains ConfigFile::load_from_path (line 250), ConfigFile::load_or_default (line 118), and backup_config_once (line 199) which implement the complete recovery chain
• crates/openlogi-core/src/config.rs – Re-exports ConfigFile and the ConfigError enum for external crate usage
• crates/openlogi-core/src/paths.rs – Defines the configuration directory resolution logic used to locate config.toml via config_dir().join("config.toml")
• crates/openlogi-desktop/src/main.rs – Entry point that handles the error tuple returned by load_or_default and logs user-visible warnings at line 78
• docs/config.example.toml – Authoritative reference for valid configuration keys and schema versions

Summary

• Automatic fallback – The ConfigFile::load_or_default function ensures the application never crashes due to malformed TOML, returning default values instead
• Error categorization – The ConfigError enum distinguishes between parse failures, obsolete fields, and unsupported schema versions for precise diagnostics
• Data preservation – The backup_config_once utility creates versioned backups (.bak files) before any overwrite operation
• Zero-downtime recovery – Users can delete or rename config.toml and restart to generate valid defaults, then manually migrate settings from backups

Frequently Asked Questions

What specific error messages indicate a TOML parse failure in OpenLogi?

When toml::from_str fails in ConfigFile::load_from_path, the system wraps the underlying parser error in ConfigError::Parse. The desktop application logs this as a warning message such as "could not load config.toml; disabling config writes" while continuing execution with default parameters.

Where does OpenLogi store configuration backup files?

According to the implementation in crates/openlogi-core/src/config/file.rs, the backup_config_once function creates backups in the same directory as the original file, using the naming convention config.toml.v{N}.bak where {N} represents an incrementing version number.

Can I programmatically detect configuration errors without loading defaults?

Yes. You can call ConfigFile::load_from_path directly rather than load_or_default. This method returns a Result that yields the specific ConfigError (Parse, ObsoleteField, or UnsupportedSchemaVersion) without automatically substituting default values, allowing your application to implement custom error handling logic.

How do I prevent configuration corruption when upgrading OpenLogi versions?

Before upgrading, verify your config.toml against the reference example in docs/config.example.toml to ensure all fields use supported keys and the correct schema_version. The ConfigError::ObsoleteField variant specifically identifies deprecated keys that must be updated to maintain compatibility with newer releases.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}