Troubleshooting

Each entry lists the symptom, the likely causes in the order to check them, and the fix.

Designer does not appear

Symptom. The product page shows the normal add-to-cart form with no designer card and no Design yours button.

Causes and fixes:

1. No template reaches the product. Check, in this order: the product's own Decoration template (Product data > General), the product's categories (Products > Categories > Decoration template), and the Site default on StitchPress > Decoration templates. For a variable product the template must be on the parent product.
2. The template is not complete enough to use. The designer only appears when the template has all of these: - at least one view with an image; - at least one zone on such a view; - at least one size, allowed by that zone; - at least one method ticked, with pricing; - a palette with at least one visible color (both built-in methods need a color for every decoration).

The template list marks a template with no method, view or zone as Incomplete, but it does not check images, sizes or the palette. Open the template and check each item. 3. The template's stored data cannot be read. The list shows Config unreadable. Restore the template from a backup, or rebuild it. 4. The product has no add-to-cart form. The designer sits inside the add-to-cart form, so an out-of-stock, unpurchasable or price-less product shows nothing. Give the product a price and stock. 5. The theme or page builder skips WooCommerce's add-to-cart form. On classic themes StitchPress prints into the woocommerce_before_add_to_cart_button hook. On block themes it injects itself into the woocommerce/add-to-cart-with-options or woocommerce/add-to-cart-form block. A page builder template that draws its own buy button without either one gives StitchPress nowhere to print. Switch the product template to one that uses WooCommerce's add-to-cart form or block, or ask your developer to fire the hook (the block list can be extended with the stp_capture_launcher_blocks filter). 6. A script optimizer broke the designer. "Delay JavaScript", "combine JavaScript" or "remove unused CSS" features can stop the designer starting. See Caching plugins and the designer. 7. Custom code turned it off. A callback on stp_resolve_template_for_product or stp_capture_usable_config that returns null hides the designer.

Text shows in a fallback font

Symptom. Customer text in the designer, the cart preview or the Job Jacket is drawn in a generic face instead of the font chosen.

Causes and fixes:

1. No font is uploaded. Without fonts there is no font choice and text is always drawn in a fallback face. Upload fonts under StitchPress > Fonts.
2. The font was deleted. The Job Jacket says the recorded font "is no longer in the font library". Upload the font again; it gets a new ID, so old orders still show the fallback but name the original font. Deactivating a font (instead of deleting it) keeps old orders printing in it.
3. The browser cannot load the font file. Fonts are served from wp-content/uploads/stp-fonts/. If your uploads are served from a CDN or another domain, the browser blocks the font unless that domain sends an Access-Control-Allow-Origin header for your site. A security rule or server configuration that blocks .woff2, .woff, .ttf or .otf files has the same effect. Open the browser's developer tools, Network tab, reload, and look for the font request failing.
4. An optimization plugin removed the font CSS. StitchPress prints its @font-face rules inline. A "remove unused CSS" feature can strip them; exclude StitchPress (see Caching plugins).
5. The designer's own interface font looks different. That is the skin's UI font, which inherits from your theme by default. It does not affect the customer's text. See Skins.

Upload rejected

The customer sees one of these messages in the designer:

The exact reason for a type rejection is written to the PHP error log when WP_DEBUG is on. Customers never see technical detail.

Rejected uploads are also written, with the reason, to the StitchPress log (WooCommerce > Status > Logs, source stitchpress).

Size refused at add to cart

Symptom. Adding to cart fails with "The design for "Front" was drawn at Large, but a different size was submitted. Please reopen the designer and try again."

Cause. The zone has a physical width, so the size comes from how large the customer drew the design (Drawn size). The size sent with the order disagreed with the drawing. StitchPress refuses rather than guessing which one the customer meant. This usually means the page was running an old copy of the designer script (a cached page or a script optimizer) or the template changed while the customer was designing.

Fix. Ask the customer to reopen the designer and add again. If it repeats, purge your page cache and any script optimization cache, and check the caching exclusions.

Related messages, with the same fix: "The drawn size for "..." is outside what that area allows" and "The design in "..." was drawn outside that area".

Rate limit messages behind a proxy or Cloudflare

Symptom. Customers see "Too many uploads from your connection", "Too many designs have been saved from this connection" or, on the proof page, "Too many attempts from your connection", even though they uploaded little. Proof approvals all record the same IP address.

Cause. StitchPress counts visitors by the connection's IP address as PHP reports it (REMOTE_ADDR). Behind Cloudflare, a load balancer or a reverse proxy that is not configured to pass the real address, every visitor appears to come from the proxy, so the whole shop shares one limit (20 uploads per hour by default). StitchPress does not read X-Forwarded-For or CF-Connecting-IP on its own, because anyone can send those headers to a server that does not strip them.

Fix 1, at the web server (recommended). Configure the server to restore the visitor's address from the proxy, trusting only the proxy's IP ranges. Then REMOTE_ADDR is correct for WordPress, WooCommerce and StitchPress alike.

• nginx: set_real_ip_from for each Cloudflare range, plus real_ip_header CF-Connecting-IP;
• Apache: mod_remoteip with RemoteIPHeader CF-Connecting-IP and RemoteIPTrustedProxy (or RemoteIPTrustedProxyList) for the Cloudflare ranges.

Cloudflare publishes its current ranges at cloudflare.com/ips. Your host can usually turn this on for you.

Fix 2, in code. If you cannot change the server, and the server only accepts traffic through the proxy, return the proxy's header from both IP filters:

$stp_real_ip = function ( $ip ) {
    return isset( $_SERVER['HTTP_CF_CONNECTING_IP'] ) ? sanitize_text_field( wp_unslash( $_SERVER['HTTP_CF_CONNECTING_IP'] ) ) : $ip;
};
add_filter( 'stp_artwork_client_ip', $stp_real_ip ); // uploads and Save design
add_filter( 'stp_proof_client_ip', $stp_real_ip );   // proof decisions

Do not use this on a server reachable directly: a visitor could send any address in that header and bypass the limit.

If the limits are simply too low for your traffic, raise Uploads per hour under StitchPress settings > Customer artwork.

Proof link expired or invalid

What the customer sees, and what to do:

Also check that the link points at the live site: a proof sent from a staging copy opens on staging.

Job Jacket print clipping

Symptom. The printed or saved Job Jacket is cut off at an edge, or a section is split oddly.

Fixes:

1. In the print dialog, choose the paper you load: Letter or A4. A mismatch is the most common cause.
2. Set Margins to Default. The sheet adds its own 12 mm margin; "None" or a custom minimum lets printers crop the edge.
3. Leave Scale at Default or 100%.
4. Turn off Headers and footers if they overlap the content.
5. Turn on Background graphics so color swatches print.
6. Use Save as PDF to see what the sheet produces without your printer's own margins.

Each line item starts a new page and the sheet tries to keep each placement on one page. A single placement taller than a page (for example a very long note) still breaks across pages.

Cron not running

Symptom. wp-content/uploads/stp-artwork/ keeps growing with artwork that was never ordered, or stp-previews/ grows without limit.

Cause. The daily cleanup (stp_artwork_gc) and, when you set one, the retention task (stp_privacy_retention, see Privacy) run on WP-Cron. WP-Cron only runs when someone visits the site, and not at all when DISABLE_WP_CRON is set without a real cron job replacing it.

Check:

• Tools > Site Health reports late or failed scheduled events.
• With WP-CLI: wp cron event list should show stp_artwork_gc (and stp_privacy_retention when retention is on). Run one by hand with wp cron event run stp_artwork_gc.

Fix. Add a real cron job that calls wp-cron.php every 5 to 15 minutes (most hosts have a setting for this), or run wp cron event run --due-now from the system cron. Each run inspects up to 200 files, so a large backlog takes several days to clear. Files referenced by an order, a live cart or a saved cart are never deleted, whatever the age.

Caching plugins and the designer

Page caching is fine: product pages can be cached. The designer asks for a fresh security token (admin-ajax.php?action=stp_capture_nonce) when it opens, so a cached page does not break uploads or add to cart.

Check these exclusions in your caching or optimization plugin, and at your CDN:

1. Do not cache AJAX requests: wp-admin/admin-ajax.php and URLs with ?wc-ajax=. Most plugins exclude them by default.
2. Do not cache the proof page and saved-design links: URLs with the query parameters stp-proof or stp_design. StitchPress sends no-cache headers on them, but some caches ignore headers.
3. Exclude StitchPress from JavaScript delay and combine features. The designer starts from a small inline boot script and loads assets/js/capture.js from the plugin folder. Exclude capture-boot, capture.js and stitchpress. If your site's Content Security Policy forbids inline scripts, the stp_inline_boot filter (return false) loads the boot script as a file instead.
4. Exclude StitchPress CSS from "remove unused CSS": assets/css/capture.css, capture-boot.css and the skin file under skins/. Those styles are used by elements the script creates after load, which unused-CSS scanners cannot see.
5. Purge caches after updating StitchPress, after changing a template, and after changing the skin.

Where to find logs

• WooCommerce > Status > Logs, source stitchpress. StitchPress writes errors and warnings there. Turn on Debug log (StitchPress settings > Advanced) for detailed lines when support asks for them, and turn it off again afterwards. Email addresses are masked in every line.
• Order notes. Proof uploads, sends, approvals, change requests, holds and releases are written to the order notes. If a design record could not be saved onto an order line, the Job Jacket says so and an order note holds the detail.
• The PHP error log. With WP_DEBUG on, the reason for each rejected artwork upload is written there.

• Tools > Site Health for scheduled-task problems.

• StitchPress > System status is the first place to look: pass/fail checks for the WordPress, WooCommerce and PHP versions, HPOS mode, the upload folders, scheduled tasks and known conflicts, with a copy button for the report that support asks for.

Related

• Install
• Templates, views and zones
• Palettes and fonts
• Proofs
• Developers