Why Character Cards Break
The most common cause of 'broken' cards isn't a bug in the card itself, but rather the way it was handled. Most social media platforms (Discord, X, Reddit) and image hosting services use aggressive lossy compression. During this process, 'non-essential' data chunks like tEXt and zTXt—where your character data lives—are often stripped away to save bandwidth.
Understanding why this happens is the first step to preventing it. PNG files are made up of chunks. Some chunks contain pixel data, others contain metadata. Social media platforms often strip metadata chunks because they think they're not important. But for character cards, those metadata chunks are everything. They contain the character's name, description, personality, and dialogue. Without them, the card is just a picture.
Identifying Stripped Cards
If you upload a card to our converter and see 'No metadata found,' the first step is to check the file size. A character-rich PNG is usually slightly larger than a standard image of the same dimensions. You can use our 'Extract JSON' tool to perform a binary sweep. If the tool returns a null result, the metadata has likely been permanently removed by a third-party host.
Another way to check is to open the card in a text editor. If you see gibberish or random characters, the file might be corrupted. If you see readable text, the metadata might still be there but in a different format. Our converter can handle both cases.
Manual Metadata Recovery
If you have the original JSON definition but a broken PNG, you can manually re-embed the data. By using a tool that supports raw chunk injection, you can create a new 'container' for your character. Our 'Any to TavernAI PNG' tool is designed specifically for this purpose—simply paste your JSON, upload a fresh image, and we will handle the binary alignment for you.
Check and Repair a Card Automatically
To find out exactly what is wrong, load the card into the Character Card JSON Validator. It reports the line and column of any JSON error and checks the V1, V2 or V3 fields. To fix it, use the Broken Card Repair tool: it repairs invalid JSON, wrong V2/V3 structure and damaged PNG metadata, lists every change it makes, and gives you a clean JSON or PNG. Both run in your browser, so the card is never uploaded. Repair cannot bring back data that was stripped or cut off, so keep the original file.
Best Practices for Preservation
Metadata loss is a common problem, and it is usually caused by how a platform handles the file. Following these best practices can help you avoid it.
To prevent data loss, always share character cards as 'Documents' or within ZIP archives. This prevents hosting platforms from touching the internal structure of the file. Additionally, maintaining a local backup of the raw JSON definition ensures that even if the image container is corrupted, the 'soul' of the character remains intact and portable.
Preventing Future Issues
Once you've fixed a broken card, you need to prevent it from happening again. Here are some practical tips:
- Always keep a JSON backup: Save the raw JSON definition of your character in a separate file. If the PNG breaks, you can always recreate it.
- Use trusted sharing platforms: Some platforms are better than others at preserving metadata. Discord is one of the best, as long as you send files as 'Documents'.
- Test before sharing: Before you share a character card, test it in your preferred platform. Make sure it loads correctly and contains all the metadata.
- Version control: If you're making changes to a character, save each version as a separate file. This way, you can always go back to an earlier version if something goes wrong.