ConnectWyze

Troubleshooting

Quick-reference index for diagnosing and fixing the most common issues across ConnectWyze Creative Automation.

What it is

This page is the top-level troubleshooting reference. Each section covers a symptom category and points you to the specific fix or the per-feature page with full detail.

Use the table of contents below to jump to your symptom:

Font rendering issues

Symptom Cause Fix
Font renders in the editor but not in the generated image The font weight or style variant you selected does not exist in that font. Check the font's available weights on fonts.google.com. Use a weight that is listed as available.
Text appears as boxes or missing glyphs A CJK or special-script font subset was not loaded before the render snapshot was taken. The renderer waits for document.fonts.ready after all CSS and Unicode-range subsets are parsed. If still failing, confirm the font file contains the required Unicode range.
Custom font looks different in the generated image versus the editor The font ships OpenType stylistic alternate features (ss01 / aalt) that newer Chromium versions auto-apply. Both the editor and render engine disable ss01 and aalt by default. If you see a difference, contact [email protected] with the template ID.
Custom font is not loading at all (generated image uses fallback) The font URL is served from a domain that requires proxying for CORS. Ensure the font storage domain appears in the needsProxy() check. Custom fonts hosted on R2 .r2.dev domains require the /api/font-proxy route. Contact support if the domain is new.
Font weight renders as bold or italic unexpectedly The font variant listed in the template does not exist, and the browser synthesizes bold/italic. Select a weight that actually exists in the font. Avoid relying on browser font synthesis for generated images.

For deeper detail, see Templates → Troubleshooting.

Image proxy and CORS failures

Symptom Cause Fix
Source data source images fail with CORS error or 403 ConnectWyze's render servers (Hetzner ASN) are blocked by the image host's CDN or bot protection. Enable the URL proxy for the affected data source. In the data source settings, turn on Use proxy for image fetching. ConnectWyze routes the request through its proxy layer automatically.
Data source sync reports 403 on image fields Proxy is not yet enabled for this data source, or the domain is not in the proxied domains list. In data source settings, enable Use proxy. If the domain is new, contact support to add it to the allowed list.
Custom font CORS failure after switching storage provider The new storage provider's domain is not in the proxy allowlist. Update needsProxy() in the font loading code to include the new domain. This requires a code change — contact support.
Mirrored image URLs return 404 after storage migration Image was mirrored to the old provider before migration. Re-mirror the data source (POST /api/creative/data-sources/{id}/mirror) to re-upload assets to the current provider.

Slow renders

Symptom Cause Fix
Individual image takes >10 seconds The render worker is under load, or the template has many external image layers that are being fetched fresh. Retry after a delay. If consistently slow, the disk image cache on the worker may need warming — the first render of a cold URL is always slower.
Large run takes much longer than expected The run is being processed sequentially or the worker pool is saturated. Check Runs for concurrent active runs. Large batches are expected to take proportionally longer. JPG output is ~3× faster than PNG — switch the workflow output format to JPG if PNG is not required.
Multi-artboard run is slow Artboards are being rendered in separate browser contexts. Multi-size templates rendered via workflow use a shared browser context and are substantially faster than calling the API once per artboard. Ensure you are using the workflow path for bulk multi-artboard work.
Preview render is slow Local Playwright fallback is active (render worker URL not configured). In production, previews route through the render worker. If you are on a local development environment, preview latency will be higher.

Failed runs and stuck runs

Symptom Cause Fix
Run stays PENDING / In Queue for more than a few minutes Render worker is unavailable or all worker slots are occupied. Check the render worker status. Runs pending for more than 60 minutes are automatically marked FAILED.
Run shows PARTIAL Some data source items failed during rendering. Open the run in Dashboard → Runs, expand the item list, and review per-item error messages. Fix the root cause (bad URL, missing variable, unsupported font), then re-run the workflow.
Run shows FAILED immediately after creation Task-build phase failed. Common causes: data source has no active items, template is archived, workspace is out of credits. Check the run error message and the workspace credit balance.
Run shows as stale (warning indicator) The run has been PROCESSING for more than 15 minutes with no activity. The worker may have lost the task. Cancel the run and re-run the workflow. If this recurs, contact support with the run ID.
Run was cancelled but some images are still in Creatives The render worker completed some tasks and flushed results before the cancellation signal arrived. Expected behaviour. Creatives contains only fully written rows. Re-run the workflow to fill in any missing images.

For full run status reference, see Runs and Creatives → Run status reference.

Credit exhaustion

Symptom Cause Fix
Run stops mid-execution with credit error The workspace ran out of credits while the run was processing. New render tasks are not accepted once the balance reaches zero. Top up credits (contact your workspace admin or [email protected]), then re-run the workflow for the remaining items.
402 Insufficient credits on every API call The workspace credit balance is at zero. Top up credits. Cache hits do not consume credits — only fresh renders do.
Credits depleted faster than expected Multiple concurrent workflows or API calls may be consuming credits in parallel. Review the Credit Usage history in workspace settings to identify the highest-consuming workflows. Consider scheduling large runs during off-peak hours to avoid concurrent depletion.
Background removal credits higher than expected Each unique combination of image URL and post-processing options counts as a separate cache entry and costs 1 credit. If crop padding or shadow settings were changed between runs, the cache was invalidated. Standardise post-processing settings before large runs. Changing only the CSS shadow style (not SSN modes) does not change the cache key and costs no additional credits.

Missing or delayed webhook callbacks

Symptom Cause Fix
Run status never transitions to COMPLETED The render worker could not reach the render callback endpoint (POST /api/webhooks/render-callback). Ensure the app server is reachable from the render worker. When testing locally, the render worker cannot reach localhost — always test webhook-dependent flows from the production environment.
Webhook for run completion fires but downstream system received no data The outbound webhook (AutomationSlackConfig or custom webhook) may have a network timeout. Check Slack notification settings and any custom webhook URLs in your workflow settings. Webhook delivery is best-effort.
Progress bar regresses (count goes down then up) The render worker sends multiple overlapping progress callbacks. ConnectWyze uses GREATEST(current, incoming) to ensure progress counters only move forward. If you observe regression in the UI, it is a display refresh timing issue — the final value is always the highest received.

Generated images look different from the editor

Symptom Cause Fix
Output image has different text layout than the editor preview A font metric difference between the editor's Chromium and the render worker's Chromium version. Both environments use the same HTML from template-to-html.ts. If you see a discrepancy, capture a screenshot from both and contact [email protected] with the template ID.
Image layer is cropped differently Focal point settings differ between what the editor shows and what the workflow uses. Verify the image layer's focal point in the template editor. The focal point can also be overridden per-render via the focalPoints field in the API.
Colors look different JPG compression introduces slight color shift, particularly in gradients. Switch the workflow output format to PNG for color-critical work, accepting the slower render time.

For the full rendering alignment model, see Templates.

Background removal issues

Symptom Cause Fix
BG removal output has white fringe around subject The inference model left partial background pixels. Increase the cropPadding value in the data source's post-processing settings, which gives auto-crop more room.
SSN shadow looks wrong or has artifacts SSN soft-shadow parameters (intensity, softness, light angle) need tuning for this subject type. Adjust the Shadow tuning sliders in the data source settings and re-process a test item.
Cache hit rate is low Source URLs change between runs (e.g. signed URLs, query strings that rotate). Use stable canonical URLs as data source image values. Signed URLs with rotating tokens defeat the SHA256 cache key.

For full background removal documentation, see Background Removal.

API errors

Status Error Fix
401 Invalid API key Key is inactive, expired, or not found. Check the key status in Dashboard → API Keys.
402 Insufficient credits Workspace has no render credits. Top up credits. See Credit exhaustion above.
403 Template not allowed The API key's template restriction list does not include this template. Edit the key to allow the template, or use a key without template restrictions.
429 Rate limit exceeded Per-minute request rate exceeded. Response body includes retryAfter (seconds). Back off for retryAfter seconds. Raise the key's rate limit in the key settings if needed.
400 Legacy v1 templates The template was created in a deprecated editor version. Recreate the template in the current editor.
500 Failed to generate image Server-side render error. Retry once. If it persists, contact support with the template ID and request payload.

For full API reference, see API Keys and Generate API.

Still stuck?

Email [email protected] with:

  • The URL of the page where you see the issue
  • The run ID or template ID (from the URL bar)
  • A screenshot or description of the expected versus actual result