Beta - Early access - we'd love your feedback! Become a beta tester →
Needlework Studio

FAQ & Troubleshooting

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

Some features on this page require the Full Version.

Desktop App

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.

Server & Docker

The questions in this section apply to self-hosted server deployments only. The desktop app handles all of this automatically.

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 server 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:6850. (The desktop app does not require this step - it logs in automatically.)

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.

I created a user but I don't see the Manage Users option

You need to promote your account to admin first. Run manage_users.py admin from the terminal:

python3 manage_users.py admin

For Docker:

docker compose exec needlework-studio python manage_users.py admin

Alternatively, set ADMIN_USERNAME=your_username in your docker-compose.yml. Once promoted, you'll see a "Manage Users" link in the Settings page.

Why does user creation ask for an email?

The manage_users.py create command requires an email address in addition to username and password. The email is used for account identification and must contain '@'. If you're the only user, any valid email format works.

Port 6850 is already in use, how do I change it?

Set the PORT environment variable. In Docker, add - PORT=8080 to the environment section and update the ports mapping. For manual installs, run:

PORT=8080 python app.py

Or set it in your gunicorn command.

How do I update to the latest version?

For Docker:

docker compose pull && docker compose up -d

For the desktop app: download the latest installer from the Downloads page. Your data is preserved across updates.

Patterns & Import

My PDF did not parse correctly

The PDF importer supports image-based, text-based, and colored rectangle chart formats with DMC or Anchor thread legends. PDFs exported by Needlework Studio itself are always re-imported with 100% accuracy.

For third-party PDFs, the importer works best with digitally-generated cross-stitch charts (the kind produced by pattern design software). Scanned or photographed charts and hand-drawn patterns are not supported. If the import fails, you will see a specific error message explaining the issue. If the result looks wrong:

  • Check that the PDF contains a standard symbol grid and a color legend with thread numbers.
  • 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 another cross-stitch program?

If the program can export to OXS (Open Cross Stitch) format, import that directly - it preserves full stitches, part stitches, backstitches, French knots, beads, and per-entry brand attribution. Otherwise export to PDF and use the PDF importer, which handles digitally-generated charts. As a last resort, 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 duplicate a pattern before making major changes to keep a backup copy.

LAN Share (phone & tablet)

I scan the QR code and the page hangs / never loads

This is usually a Wi-Fi problem rather than an app problem. The connection request reaches your computer, but the response cannot make it back to the device. The most common causes:

  • Private Wi-Fi Address is on. iOS rotates a randomized MAC address per network by default, and many mesh routers drop or misroute packets to those addresses. On the phone or tablet: Settings → Wi-Fi → tap the ⓘ next to your network → toggle Private Wi-Fi Address off → Rejoin. This is the most common cause we have seen.
  • The two devices are on different networks. Guest networks and split 2.4/5 GHz SSIDs are usually isolated from each other. Confirm both devices show the same network name in their Wi-Fi settings.
  • AP isolation / client isolation is enabled on your router. This is a router setting that prevents devices on the same Wi-Fi from talking to each other. Look for it in your router admin under wireless or guest network settings and turn it off for your main network.
  • Stuck Wi-Fi association. Toggle Wi-Fi off then on on the phone or tablet to force it to re-attach to the access point.

I see "401 Pairing Required" after scanning the QR code

This was a bug in versions before 0.8.2 where iOS Safari would drop the session cookie on the redirect back to the home page. Update the desktop app to 0.8.2 or later from the downloads page and try again.

I see a "This Connection Is Not Private" warning

That is expected on the first visit. The desktop app generates a self-signed certificate so it can serve LAN share over HTTPS, which is required for offline pattern viewing. Tap Show Details → visit this website → Visit Website. You only need to do this once per device. Nothing leaves your network.

The pairing link expired

Pairing tokens are valid for 5 minutes and can only be used once. Generate a new QR code on the desktop's share page and rescan.

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.