> ## Documentation Index
> Fetch the complete documentation index at: https://hyperlocalise.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Common errors

> Troubleshoot frequent setup, config, provider, and sync failures.

## `i18n.yml already exists; use --force to overwrite`

Cause: running `init` where config already exists.

Fix:

```bash theme={null}
hyperlocalise init --force
```

## `storage config is required`

Cause: `sync` command used without top-level `storage` config.

Fix: add `storage.adapter` and `storage.config` in `i18n.yml`.

## `unsupported output format`

Cause: wrong `--output` value.

Fixes:

* `status`: only `csv`
* `sync`: `text` or `json`

## `unsupported file extension` during `run`

Cause: a mapped source or target file uses an extension not supported by the local parser.

Fixes:

* use one of: `.json`, `.jsonc`, `.yaml`, `.yml`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts`, `.cts`, `.properties`, `.xml`, `.resx`, `.arb`, `.xlf`, `.xlif`, `.xliff`, `.po`, `.html`, `.liquid`, `.md`, `.mdx`, `.strings`, `.stringsdict`, `.xcstrings`, `.csv`, `.ftl`
* verify bucket `from` and `to` paths resolve to the expected file names

For `.xcstrings`, ensure the catalog has a `strings` object and either a source-language localization for variant/substitution entries or simple catalog keys that can be used as source text.

## Provider auth failures

Cause: missing/invalid env token.

Fix: re-export token in the same shell session and rerun.