FAQ & Troubleshooting

Answers to common questions and solutions for issues you may run into.

Desktop App

macOS says the app is damaged or cannot be opened

The macOS build is not signed with an Apple Developer certificate, so Gatekeeper blocks it on first launch. To open it:

Right-click (or Control-click) the app in Finder.
Select Open from the context menu.
Click Open again in the confirmation dialog.

You only need to do this once. After the first launch, macOS remembers your choice.

Where does the desktop app store my data?

The desktop app stores all data (database, images, settings) locally on your machine in the application's data directory. On macOS this is in ~/Library/Application Support/needlework-studio, on Windows in %APPDATA%\needlework-studio, and on Linux in ~/.config/needlework-studio. No internet connection or server is required.

Installation & Docker

I ran init_db.py and lost all my data

init_db.py drops and recreates the entire database from scratch. It is meant for first-time setup only. If you ran it on an existing installation, your data is gone unless you have a backup. See Administration for backup procedures to avoid this in the future.

The app starts but I cannot log in

You need to create a user account first. For Docker:

docker compose exec needlework-studio python3 manage_users.py create

For manual installs:

python3 manage_users.py create

Follow the prompts to set a username and password, then log in at http://localhost:6969.

How do I reset my password?

Use the manage_users.py script with the password command:

python3 manage_users.py password

For Docker:

docker compose exec needlework-studio python3 manage_users.py password

Can multiple users share one server?

Yes. Each user has their own account, thread inventory, and pattern library. Create additional accounts with manage_users.py create. Data is isolated between users.

Patterns & Import

My PDF did not parse correctly

The PDF importer works best with digitally-generated cross-stitch charts (the kind produced by pattern design software). Scanned or photographed charts, hand-drawn patterns, and heavily stylized PDFs may not parse accurately. If the result looks wrong:

Check that the PDF contains a standard symbol grid and color legend.
Try a different PDF of the same pattern if available (some sellers offer multiple formats).
As a fallback, use the Image-to-Pattern converter: take a screenshot of the chart and convert it as an image.

Can I import patterns from PC Stitch or other software?

If the software can export to OXS (Open Cross Stitch) format, you can import it directly. Many cross-stitch programs support OXS export. Otherwise, export to PDF and use the PDF importer, or export a chart image and use the Image-to-Pattern converter.

The color matching looks wrong after import

OXS files contain explicit thread references (e.g. "DMC 310"), so colors are mapped directly to threads in your library. If a thread number in the file is not recognized, the raw hex color is used instead. For the Image-to-Pattern converter, colors are matched to the closest DMC thread using the CIEDE2000 perceptual color distance algorithm, which usually produces good results but may not be perfect for every color. In either case, you can open the pattern in the editor and use the Replace Color tool to swap any color for a better match.

Editor & Viewer

How do I see all keyboard shortcuts?

Press ? in either the pattern editor or the pattern viewer to open a help overlay listing all available keyboard shortcuts.

My unsaved changes were lost

The editor autosaves to your browser's local storage every few seconds. If you close the tab accidentally, reopening the editor should prompt you to recover your work. Autosave data is kept for 7 days. However, clearing your browser data or using a different browser will lose the autosave. Always use Ctrl+S to save to the server.

The pattern looks blurry or pixelated

Check your zoom level. At very low zoom levels, the chart shows simplified color blocks without symbols or fine detail. Zoom in (scroll wheel or + key) to see individual stitches clearly. At 100% and above, each stitch cell is rendered at full detail.

Do my settings carry over between sessions?

Yes. Most interface preferences are saved in your browser's local storage and restored automatically the next time you visit. This includes your gallery view mode (grid or list), status and category filters, legend sort order, gridline and symbol toggles, brush size, mirror mode, thread brand selection, and calculator settings. Note that these are per-browser - if you switch to a different browser or clear your browser data, preferences will reset to defaults.

Sync

The sync icon is red / sync is failing

A red sync icon means the desktop app cannot reach the server. Check that:

The server is running and accessible at the URL you configured.
Your network connection is working (try opening the server URL in a browser).
The port is not blocked by a firewall.
If you changed the server's URL or port, unpair and re-pair with the new address.

I made changes on both devices and one was overwritten

Needlework Studio uses a last-write-wins strategy based on timestamps. The most recently modified version takes precedence. To avoid accidental overwrites, sync frequently and avoid editing the same pattern on multiple devices at the same time. You can also fork a pattern before making major changes to keep a backup copy.

Browser Compatibility

Needlework Studio's web interface is tested on current versions of:

Chrome / Chromium (version 90+)
Firefox (version 90+)
Safari (version 15+)
Edge (version 90+)

The app uses HTML5 Canvas for pattern rendering and localStorage for autosave and preferences. JavaScript must be enabled. Mobile browsers work but the editor is best used with a mouse or trackpad due to the precision required for placing individual stitches.

Needlework Studio is also PWA-compatible. On iPad or other tablets, you can tap Share > Add to Home Screen in Safari (or Install app in Chrome) to add it as a standalone app with no browser chrome. This requires a self-hosted server to be running.