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

# Merge Conflict Error • AI Agents Framework

> MergeConflictError: raised when --merge targets an existing but un-parseable YAML file.

# MergeConflictError

> Defined in the [**auto**](../modules/auto) module.

<Badge color="red">Exception</Badge>

Raised when `--merge` targets an existing but un-parseable YAML file. Before raising, the wrapper writes a collision-safe backup of the original so no data is lost, then propagates out of `convert_and_save` to the CLI — **no write happens** and the user's file is preserved.

Inherits from the built-in `Exception`.

## When it is raised

`AutoGenerator.merge_with_existing_agents` and `WorkflowAutoGenerator.merge_with_existing_workflow` catch `yaml.YAMLError` explicitly and raise `MergeConflictError`. `OSError` / `PermissionError` propagate unchanged.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#8B0000', 'primaryTextColor': '#fff', 'primaryBorderColor': '#710101', 'lineColor': '#189AB4', 'secondaryColor': '#189AB4', 'tertiaryColor': '#fff' }}}%%

graph LR
    merge["--merge"] --> read["Read target YAML"]
    read --> err["yaml.YAMLError"]
    err --> bak["Write &lt;file&gt;.&lt;stamp&gt;.bak"]
    bak --> raise["Raise MergeConflictError"]
    style merge fill:#8B0000,color:#fff
    style read fill:#189AB4,color:#fff
    style err fill:#F59E0B,color:#fff
    style bak fill:#189AB4,color:#fff
    style raise fill:#8B0000,color:#fff
```

## Message

```text theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
Refusing to overwrite un-parseable <path>: <YAMLError>. Original preserved at <path>.<stamp>.bak. Fix the file or re-run without --merge.
```

If the backup copy itself fails (`shutil.copy2` error), the message is instead:

```text theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
Backup failed; original left untouched at <path>.
```

## Resolution

Fix the reported parse error in your YAML, or re-run **without** `--merge` to regenerate the file from scratch.

## Usage

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.auto import AutoGenerator, MergeConflictError

generator = AutoGenerator(topic="add a QA reviewer")
try:
    generator.convert_and_save(json_data, merge=True)
except MergeConflictError as exc:
    print(exc)  # original agents.yaml is intact; a .bak was written
```

## Source

<Card title="View on GitHub" icon="github" href="https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai/praisonai/auto.py">
  `praisonai/auto.py`
</Card>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Auto Generator" icon="brackets-curly" href="./AutoGenerator" />

  <Card title="Merge safety (CLI)" icon="shield-check" href="/docs/cli/auto#merge-safety" />

  <Card title="Auto-Generator Safety" icon="shield" href="/docs/features/auto-generator-safety" />

  <Card title="merge_with_existing_agents" icon="function" href="../functions/AutoGenerator-merge_with_existing_agents" />
</CardGroup>