Skip to content

Troubleshooting Media Synchronization

This page is for administrators and technical staff responsible for the portal server, deployment, and network. For setup and everyday use, see Automatic Media Synchronization.

Start with the Business Central Log

  1. Open Business Portals - Log in the company that ran the job.
  2. Filter Source to Portal media synchronization.
  3. Read the individual portal failure as well as the summary. 2 failed means two target attempts failed; their causes may differ.
  4. Record the time, target URL or portal reference, operation, and HTTP status where provided.
  5. Compare the result with the portal's server log. Account for time-zone differences; hosting logs may show UTC.

The standard Job Queue history can show Success even when a portal failed. The job handles portal failures separately so later portals and scheduled runs can continue.

Do not include the Media Sync key, encrypted configuration values, request signatures, or complete configuration files in a support ticket. Share the relevant diagnostic message and remove sensitive information.

Configuring the Portal

The receiving endpoint is <portal-base>/MediaSync.ashx. Deploy the updated portal handler and library together with the compatible Business Central extension.

Install the copied encrypted key as the value of MediaSyncKey in the active configuration file:

Portal Build and Configuration Active File
Release using the version 2.7.x.x and above configuration Auth.config
Release using the version below 2.7.x.x configuration CustomSettings.config

Listed portals also validate their configured PortalReference against the portal record. Requests to the selected setup Endpoint use standalone authentication and do not require a separate reference in Module Setup.

The Media Sync key is independent of other secrets. Managed App Registration portals receive key updates through their publishing connection, self-hosted portals require manual installation of the encrypted value. A failed managed update can be retried with Update Media Sync Key on Portals.

Warning

ENC:v1 values are decryptable by the portal. They must still be protected as credentials, including when transferring them to a self-hosted server. Do not publish them in browser-facing settings or logs.

Common Messages and HTTP Responses

Message or Status Checks and Next Steps
No portals updated, unsupported, or failed Check whether the portal list contains non-empty URLs and whether the selected setup Endpoint has a URL.
Invalid URL Use the portal base address. Remove page names, credentials, query strings, fragments, trailing punctuation, and unintended spaces. HTTPS is the default.
Transport failure Check Allow HttpClient Requests for the extension, DNS resolution, firewall rules, certificate trust, and reachability from the Business Central server. Browser access from an administrator's PC does not establish server access.
HTTP 400 Check the operation and portal diagnostics. A request arriving over HTTP is rejected unless the signed Allow HTTP Media Sync option is enabled. IIS can also reject an invalid hostname before the handler runs.
HTTP 401 Verify the active MediaSyncKey, listed portal reference where applicable, and clock synchronization. Check the portal's authentication diagnostic to identify the failed check.
HTTP 403 Check IIS, hosting, proxy, and access restrictions for MediaSync.ashx.
Unsupported portal / capability HTTP 404 or 410 Confirm the updated handler and library were deployed at the configured base path. A missing endpoint is skipped; this does not mean media was refreshed.
HTTP 409 Another refresh may have published first, or a request was replayed or sent out of sequence. Let the next hourly run retry the complete refresh, or retry manually after competing updates finish.
HTTP 413 Inspect server and proxy request-size limits. The protocol accepts a maximum request body of 1 MiB; do not raise only the application limit without checking the other layers.
HTTP 500 Check portal diagnostics, filesystem permissions, conversion failures, and available disk space. Keep the current cache while investigating.
HTTP 502 through a tunnel or proxy Inspect the proxy's own error details and upstream connection. Confirm the local portal is running on the configured port and scheme. A 502 alone does not establish rate limiting.
Invalid synchronization response The endpoint may have returned a login page, HTML error page, redirect, or incompatible response. Check proxy rules and the deployed version.

Reading Portal Diagnostics

The handler writes authentication and synchronization failures through the portal application's trace logging. Enable application error logging on the host and reproduce one run. On Azure App Service for Windows, use Application logging (Filesystem) at Error, then check Log stream or LogFiles/Application through Kudu. This is separate from the standard IIS HTTP access log.

Look for Media synchronization authentication failed or Media synchronization failed. Authentication diagnostics distinguish invalid identifier formats, timestamp failures, registration mismatches, unavailable keys, and signature mismatches. Logs deliberately omit the secret and signature; a stack trace may not include source line numbers.

A timestamp outside the allowed window means the request differs from the portal's UTC clock by more than five minutes. Check the deployed sender version and clock synchronization before changing keys.

Local Portals, Tunnels, and HTTPS

Business Central Online cannot reach the localhost address of PC. Use a reachable tunnel or hosted portal. A locally installed Business Central server must also have network access to the configured URL.

An HTTPS tunnel can forward to an HTTP upstream:

Business Central -> HTTPS tunnel -> HTTP localhost

In this arrangement, the portal sees the final HTTP connection. Either forward the tunnel to a trusted local HTTPS binding or enable Allow HTTP Media Sync. The option is carried in the request signature, adding an HTTP-allow header manually does not authenticate a request. Deploy both updated sides before testing it.

If IIS Express reports Invalid Hostname, check its site binding and the tunnel's Host-header forwarding. If the tunnel reports a gateway error, inspect its upstream error code, verify the local site directly, and confirm that IIS Express is still running.

The HTTPS/HTTP choice does not explain every failure on a separate live portal. Review that portal's individual log entry rather than relying on a combined job summary.

Understanding Storage and Cleanup

Paths below are relative to the deployed website root:

Location Purpose
temp/img and temp/video Original media folders, served until the first successful cache publication.
temp/media-cache/<guid>/img and video Complete media generations. A GUID identifies a refresh, not an individual image.
App_Data/media-sync/current Identifies the currently published generation.
App_Data/media-sync/previous Identifies the previous generation retained for recovery. Retention does not automatically restore it.
App_Data/media-sync/<guid>/ Automatic upload batches and refresh state, or temporary manual generation data.
App_Data/media-sync/<guid>.retired Records retirement time through its file modification timestamp.
App_Data/media-sync/*.nonce Replay protection for authenticated requests.
App_Data/media-sync/cleanup.timestamp Coordinates the one-minute cleanup scan interval across workers.

Existing /temp/img/... and /temp/video/... URLs are internally rewritten to the current generation. IIS must run managed modules for static requests; retain the project's runAllManagedModulesForAllRequests="true" setting. Missing files in the current generation do not fall back to old copies, so removed media is not brought back accidentally.

The current and previous generations are protected. Older generations become eligible 15 minutes after retirement. Use the corresponding .retired file's modification time, not the generation folder's creation or modification time. Original legacy folders become eligible 15 minutes after the first successful publication. Cleanup deletes those entire legacy folders, including any extra files placed there.

Successful automatic refreshes attempt to remove their uploaded .batch files immediately after publication. Manual refreshes attempt to remove their staging folder immediately on success or failure. Remaining inactive staging folders become eligible after two hours, nonce files become eligible after 15 minutes. Cleanup runs on subsequent authenticated synchronization requests or manual updates, at most once per minute. It is not an independent background task and does not run just because a user views an image.

If eligible files remain, check the current and previous pointers, the retirement timestamps, subsequent update activity, filesystem locks, and permissions. Cleanup access failures are logged as warnings and retried later. Enable warning-level application logging if you need those messages, error-only logging does not include them.

Warning

Do not delete the current generation or edit pointer files as a routine cleanup measure. A refresh temporarily needs room for existing media, incoming batches, and newly generated files. There is no hard storage quota in this feature, monitor free disk space. Repeated runs within the grace period can retain several complete generations. As long as the update done through auto generation and no files are edited, the older files will be cleaned up periodically.

Hosting and Recovery Checks

One portal must share the same writable storage for App_Data/media-sync and temp/media-cache. Storage must support exclusive file locks, file replacement, and directory moves on the same volume. Check that the application identity can create, read, move, and delete files in these locations.

Finalization converts and publishes the complete selection synchronously. Large selections must fit the host's request deadline and available memory and disk space.

If a refresh fails before publication, the current media stays available. If a connection times out after publication, Business Central can report failure even though the portal has already switched to the complete new generation. Check the pointer and visible media before concluding that publication failed. A later full refresh is safe.