Simple Object Designer Documentation
Index

Symbol Troubleshooting

This page helps you diagnose and resolve common issues with symbol download in Simple Object Designer.

Start Here: Refresh Symbols and Clear the Cache

The single most effective fix for symbol problems — and for a surprising number of publishing problems — is a full refresh with the cache cleared:

  1. If SOD prompts you to refresh symbols when the page opens, answer No
  2. Open the SOD Setup page
  3. Run Refresh Symbols
  4. When asked whether to clear the cache, answer Yes
  5. Let the download complete — it can take several minutes on a large environment

Two details matter:

  • A plain refresh is not the same thing. Without clearing the cache, stale entries are updated incrementally and problem records survive. Several errors below are resolved only by the cache-clearing variant.
  • Run it from the Setup page, not the on-open prompt. The automatic refresh triggered when opening SOD is what produces the "record already exists" errors.

Also make sure you always run SOD from the same company. Switching companies produces symbol and cache errors that look like something else.

Symptom Index

Error / symptom Section
Could not contact dynamics.com — Request timed out Request timed out
No published package matches the provided arguments No published package matches
You don't have access to this / Error 53003 Conditional Access blocks sign-in
AADSTS700016 — application not found in directory AADSTS700016
You do not have the following permission: Snapshot debugging Permission Denied
The record in table Field MetaData Hgd already exists Record already exists
The Field MetaData Hgd does not exist Field MetaData missing during publish
Extension Cache Hgd does not exist Extension Cache Hgd does not exist
DotNet ZipArchiveEntry / extraction failure Defective symbol package
A package with publisher 'Microsoft'… could not be found Package cache errors
The Anchor Table does not exist Anchor table missing after Import App
A specific field is missing A specific field is missing
Generated extension disappeared after a BC update Extension missing after a BC update

Connectivity and Service Issues

"Could not contact dynamics.com (Request timed out.)"

This is the most frequently reported symbol error, and it has several distinct causes. The AL call stack points at Symbol Management Hgd (codeunit 70310251) — DownloadFileEx, DownloadAndImportSymbolsFromApp, DownloadSymbols.

Work through these in order.

1. Allow HttpClient Requests. SOD must be permitted to make outbound calls. Go to Extension Management > Simple Object Designer by Hougaard > Configure and enable Allow HttpClient Requests.

2. Firewall / proxy. On on-premises or hybrid setups, confirm the server can reach *.dynamics.com.

3. Just retry. These timeouts are often transient. Close and reopen the Object Designer page to trigger the download again — symbols are cached as they arrive, so each attempt progresses further. First launch downloads a large volume of symbols, and on a slow connection the request may time out before finishing; the second or third attempt usually succeeds.

4. Suspect a Microsoft outage. If the checks above are correct and the timeout persists, the cause is very likely on Microsoft's side. See below.

Distinguishing a Microsoft service outage

In production environments, symbol download uses Microsoft's development / snapshot-debugger endpoint. When that service is degraded, the request fails at Microsoft's gateway:

The request for path /v2.0/production/snapshotdebugger/attach?debuggingcontext=<id>&tenant=<tenant>
failed with code GatewayTimeout. Reason: Gateway Timeout

A GatewayTimeout against the snapshotdebugger path — especially when several parties or environments are affected — indicates a Microsoft-side outage, not a permissions, network, or SOD configuration problem. It is outside both Hougaard's and your control.

Key fact: sandbox environments download symbols from a different source than production. Symbol download can work perfectly in a sandbox while failing in production, because only the production endpoint is affected. A working sandbox therefore does not rule out an outage.

What to do:

  1. Retry periodically — Microsoft fixes can take a few days to propagate fully
  2. Open a support ticket with Microsoft, quoting the failing request path and the GatewayTimeout code as evidence. This can normally be raised through your Business Central partner.
  3. Workaround: develop in a sandbox instead, then deploy the resulting .app to production. Use Export App / Import App, or copy the production environment to a sandbox. Switching to a sandbox does not change the BC version — only the symbol-download source differs.

There is also a known Microsoft backend bug that produces this same timeout even with HttpClient requests enabled. The remedy is the same: retry, wait for the Microsoft fix, or work in a sandbox meanwhile.

"No published package matches the provided arguments"

Symptom:

Could not contact dynamics.com, error ({"Message":"No published package matches the provided arguments."})

Symbol download starts, appears to progress, then fails. It may also appear when opening SOD and accepting the prompt to update symbols. The call stack references Symbol Management Hgd — DownloadFile, DownloadAndImportSymbolsFromApp, DownloadSymbols. A related error may follow on publish: The Extension Cache Hgd does not exist. Identification fields and values: App ID='{...}'.

Cause: a bug in Microsoft's backend. Not a permission or configuration problem on your side, and it can happen on a previously stable environment — even in a sandbox where SOD has made no modifications yet.

Solution: update Simple Object Designer to the latest version, which contains a workaround. The minimum fixed version is 12.0.0.555; a version older than the workaround will not help.

Update steps:

  1. Go to the Admin Center
  2. Select the environment
  3. Click Apps
  4. Update Simple Object Designer

Microsoft also fixed the underlying platform bug, but SOD's workaround does not depend on that fix reaching your instance.

Authentication Issues

Authentication Failed

Symptoms:

  • OAuth2 login window appears but authentication fails
  • Error message about invalid credentials
  • Redirect back to SOD without completing

Causes:

  • Incorrect username or password
  • Multi-factor authentication issues
  • Browser blocking pop-ups
  • Cached credentials causing conflicts

Solutions:

  1. Clear browser cache and cookies
    • Close all browser windows
    • Clear cache for the Business Central domain
    • Try again with fresh session
  2. Check pop-up blocker
    • Ensure pop-ups are allowed for Business Central URL
    • Try a different browser
  3. Verify credentials
    • Make sure you're using the correct account
    • Check that the account has BC access
  4. Try incognito/private mode
    • Opens without cached credentials
    • Can help identify cookie issues

Conditional Access Blocks Sign-In (Error 53003)

Symptoms: sign-in succeeds, then a screen appears saying "You don't have access to this. Your sign-in was successful, but does not meet the criteria to access this resource…". The error shows Error Code 53003 (or the variant 530033), often with Device state: Unregistered. Symbol download does not proceed.

Cause: a Microsoft Entra ID (Azure AD) Conditional Access policy is blocking the Simple Object Designer application. SOD authenticates using the OAuth2 Device Code flow, and Microsoft has been introducing rules that block device-code sign-in — sometimes automatically, without the tenant deliberately creating such a policy.

This is a separate layer from Business Central. It is independent of the user's SUPER or admin status: a BC super admin can still be blocked. It commonly surfaces after a tenant migration, when the new tenant's policies start applying to the SOD application.

Why the sign-in details look unfamiliar

SOD does not run on your PC. The machine pulling the symbols is Microsoft's server where Business Central runs, so the sign-in evaluated by Conditional Access originates from the Azure-hosted BC service host — not from the user's workstation. Consequently:

  • The IP address is a Microsoft Azure data centre IP, not your office network. This is expected and not an intrusion.
  • The Device Platform shown (for example "Windows 10") reflects the BC service host, not the user's machine. An "outdated OS" on the user's side is not the cause.
  • Device ID and Device Status reflect the BC backend, not your managed devices.

Resolution (requires an Entra / M365 administrator)

  1. Sign in to the Azure Portal (portal.azure.com)
  2. Go to Microsoft Entra ID > Enterprise Applications
  3. Find Simple Object Designer — app id 32787dc1-cef9-42a3-80c2-99ddc02e6a30
  4. Find the Conditional Access policy targeting this app, and either exclude the app from it, allow Device Code Flow for it, or create a grant exception
  5. Retry Refresh Symbols

To identify exactly which policy is blocking, look up the Request Id from the error in the Entra ID sign-in logs.

Best practice: scope the exclusion narrowly to the policy enforcing device platform or device compliance, rather than excluding SOD from all policies. Controls such as MFA can and should remain in place.

AADSTS700016: Application Not Found in Directory

Symptoms: starting SOD or completing device-code login produces "Login server has not returned a token" containing:

AADSTS700016: Application with identifier '<app id>' was not found in the directory '<tenant>'

Error code 700016. SOD may appear to keep working for a while despite this, but the authentication problem should still be fixed.

Cause: Microsoft changed security settings, which required Hougaard to update SOD. Older SOD versions use an application registration that is no longer valid.

Solution: update Simple Object Designer to the latest version. See Updating SOD.

Note that changing Business Central partners is not a cause of this error.

OAuth2 Device Code Not Shown

Symptoms:

  • Click Refresh Symbols but nothing happens
  • No device code or verification URL appears
  • SOD seems to hang

Causes:

  • Background poll stalled
  • Browser security settings
  • Browser extension interference

Solutions:

  1. Check pop-up blocker
    • Allow pop-ups for businesscentral.dynamics.com
    • Try disabling pop-up blocker temporarily
  2. Try different browser
    • Edge and Chrome typically work best
    • Disable browser extensions temporarily
  3. Check browser console
    • Press F12 to open developer tools
    • Look for errors in the console

Permission Issues

Permission Denied

Symptoms:

  • Authentication succeeds but download fails
  • "Access denied" or "Unauthorized" error
  • "User does not have permission" message

Causes:

  • Missing SUPER permission
  • Missing Snapshot Debugging permission (production)
  • Company-scoped permissions only
  • Delegated admin limitations

Solutions:

  1. For Sandbox environments
    • Request SUPER permission set
    • Or request D365 EXTENSION MGT
  2. For Production environments
    • Request SUPER permission set
    • Request Snapshot Debugging permission from admin
    • See Required Permissions
  3. Check permission scope
    • Ensure permissions are tenant-wide, not company-specific

"You do not have the following permission: Snapshot debugging"

Symptom: in a production environment, opening SOD or refreshing symbols fails with:

Could not contact dynamics.com, error ({"Message":"You do not have the following permission: Snapshot debugging"})

…even though the account visibly has the Snapshot Debugging permission set assigned.

Cause: the permission set line has a specific company specified instead of applying to all companies.

Solution: remove the company value from the permission set line so it is assigned tenant-wide, then retry.

New Production User Cannot Download Symbols

Symptom: after registering and installing SOD in production, launching SOD and updating symbols fails with a permission error. The call stack references Symbol Management Hgd (codeunit 70310251) — DownloadFile, DownloadAndImportSymbolsFromApp, DownloadSymbols — and Object Designer Menu Hgd (page 70310263) OnOpenPage.

Cause: in production, symbol download requires the Snapshot Debugging permission in addition to every other SOD and BC permission. Adding SOD's own permission sets — AL_COMPILER_PERM_HGD, OBJECT DESIGNER HGD, REMOTEAL_HGD — does not resolve this. Those cover SOD operation, not access to the production development endpoint.

Two options:

  1. Recommended: do not develop in production. Apply the license key to SOD in a sandbox, develop and test there, then publish to get the .app and upload it through Extension Management in production. See Environments.
  2. To develop directly in production, assign the Snapshot Debugging permission on top of all others. See Required Permissions.

Development Endpoint Not Available

Symptoms:

  • Error about development endpoint
  • "Endpoint not found" message
  • Download fails immediately after authentication

Causes:

  • Production environment without proper permissions
  • Environment configuration issue
  • BC version doesn't support the API
  • A Microsoft-side outage of the snapshot-debugger endpoint

Solutions:

  1. For Production
    • Snapshot Debugging permission is required
    • Contact your administrator
  2. Check BC version
    • Ensure BC version is 25.0 or higher
    • Earlier versions may not support the API
  3. Alternative API URL
    • If using non-standard environment, configure Alternative API URL in Setup
  4. Consider an outage
    • Symbol download in production relies on Microsoft's snapshot debugger endpoint. If that service is down, downloads fail with a gateway timeout even when permissions and BC version are correct. Use a sandbox until the service is restored — see Request timed out.

Cache and Metadata Errors

"The record in table Field MetaData Hgd already exists"

Symptom:

The record in table Field MetaData Hgd already exists.
Identification fields and values: TableNo='<number>', No.='<number>'

Appears when opening SOD or refreshing symbols. The call stack references Symbol Management Hgd — ProcessSymbols, ImportSymbol, DownloadSymbols.

Cause: the refresh is trying to insert symbol records that already exist, because the cache was not cleared first. This typically happens when the refresh runs automatically as SOD opens. Microsoft moving or changing object structures in a BC update is what creates the duplicates in the first place — it is not a problem with your data.

Solution:

  1. When SOD prompts to refresh symbols on open, answer No
  2. Open the SOD Setup page
  3. Run Refresh Symbols
  4. Answer Yes to clear the cache
  5. SOD works normally after the refresh completes

Note: updating to the latest SOD version does not fix this. The fix is to clear the cache during a manually triggered refresh.

Field MetaData Missing During Publish

Symptom: publishing fails with a "Field MetaData Hgd does not exist" error naming a table number and field number. The call stack references Build Extension Hgd (codeunit 70310250) / ExportTableExtensions.

Cause: a corrupted or incomplete symbol cache. Note that a bad symbol cache causes publish failures, not only missing objects in lists.

Solution: run Refresh Symbols from the Setup page, answering Yes to clear the cache, then republish.

If it survives that, the cause is a configuration reference rather than the cache — see Publishing Failures for the FlowField-filter and Lookup causes.

"Extension Cache Hgd does not exist"

Symptom: pressing Publish fails with an error that the "Extension Cache Hgd" record does not exist for a given App id (the message may be localized). The call stack references Modern Build Extension Hgd (codeunit 70310262) CreateModernExtensionEx and Object Designer Menu Hgd (page 70310263) ExportExtension - OnAction.

Solution: run Refresh Symbols, answer Yes to clear the cache, and publish again.

Known limitation: in one reported case, clearing the cache did not resolve the error while the Microsoft compiler was selected. The error reproduced with the Microsoft compiler and did not occur with the Legacy compiler using previously working settings. If the error persists after a cache-clearing refresh with the Microsoft compiler selected, contact Hougaard support.

Package Not Found in the Package Cache

Symptom: during publish:

A package with publisher 'Microsoft', name 'Application', and a version compatible with
'<BC version>.0.0.0' could not be found in the package cache folders

Sometimes accompanied by "Index and length must refer to a location within the string. (Parameter 'length')". The app.json platform reference may show an unexpected value such as 1.0.0.0 instead of the current BC major version.

Context: this typically follows a BC platform update and/or an SOD update, where cached symbols no longer match the required platform version.

Steps:

  1. Refresh Symbols with cache clearing, complete the full download, and publish again
  2. If it persists, check which compiler is in use (Legacy vs. Microsoft)
  3. If still unresolved, use Download Source on the Setup page and send the ZIP to support@hougaard.com

There is also a known Microsoft symbol-resolution bug behind this message, with a specific SOD workaround — the Alternative API Dependencies setting. See Publishing Failures.

Downstream Errors After a Failed Symbol Download

When symbol download or authentication fails, later errors are often consequences of the missing symbols rather than separate faults:

  • A DotNet variable has not been instantiated. Attempting to call System.IO.Compression.ZipArchiveEntry.Open in CodeUnit Data Compression Impl.: ExtractEntry — there is no downloaded zip to extract
  • A package with publisher 'Microsoft', name 'Application', and a version compatible with '<version>' could not be found in the package cache folders: ...&#.;alpackages — symbols never reached the cache

Fix the underlying authentication or download problem first; these disappear with it.

Defective Symbol Package from a Third-Party App

Symptoms: symbol download fails during extraction with a .NET runtime error (possibly localized) referencing failure to create a DotNet variable and a call to System.IO.Compression.ZipArchiveEntry.Open in Data Compression Impl.: ExtractEntry. The call stack shows "Data Compression Impl." (codeunit 421) ExtractEntry and "Data Compression" (codeunit 425) ExtractEntry, called from Symbol Management Hgd (codeunit 70310251) DownloadAndImportSymbolsFromApp / DownloadSymbols.

Cause: one of the installed extensions has a defective symbol package. App files, including their symbol packages, are specialized zip files; a malformed one breaks extraction. This is not a permissions, configuration, or BC-version problem — it reproduces across BC versions.

Known source: extensions generated by third-party tools that imitate SOD's functionality but do not produce correct app files. Apps created by the KUMAVISION API Page Creator (used to generate API pages for single tables) have been observed to produce invalid symbol packages.

Resolutions:

  1. Update SOD. SOD now detects and ignores apps produced by that tool during symbol download, after which the download completes.
  2. Workaround: uninstall the offending third-party app via Extension Management before refreshing symbols. Identify it by matching the failing symbol package to the installed extension.

Note that an app producing invalid app files may eventually be invalidated by Microsoft.

Missing Objects and Fields

Partial Download / Missing Objects

Symptoms:

  • Download completes but tables/pages are missing
  • Some extensions show in cache, others don't
  • Expected objects not in lists

Causes:

  • Download interrupted
  • Extension failed to process
  • Cache corruption
  • Extension installed after last download

Solutions:

  1. Re-download symbols with the cache cleared
    • Go to Setup > Refresh Symbols and answer Yes to the cache-clearing prompt, so stale entries are fully replaced rather than incrementally updated
  2. Check specific extension
    • Note which objects are missing
    • Check if their extension is installed
  3. Verify extension installation
    • Go to Extension Management
    • Confirm expected extensions are installed

A Specific Field Is Missing

Symptom: the right table is selected in SOD, but one particular field cannot be chosen — even though the field is plainly visible in Business Central's own page or table inspection.

Step 1: Refresh Symbols from the Setup page, answering Yes to clear the cache, so a full re-download replaces the existing cache.

Step 2 — if the field still does not appear, ask which extension owns that field and how it is distributed: an AppSource app, or something installed separately (per-tenant, partner-delivered)? A single missing field, as opposed to whole tables, usually means the owning extension's symbol package is unavailable or was not fully downloaded. Identifying the owning app is the key diagnostic.

Step 3 — accept what the symbols say. After a full refresh with the cache cleared, SOD shows exactly the fields that exist in the connected environment. If they are still absent, those fields do not exist in that table in this environment — it is not a caching problem. Verify the field names and numbers against the actual table in the target environment. Custom fields in the per-tenant range (50,000–99,999) or other custom ranges only appear when the extension defining them is installed.

"The Anchor Table does not exist"

Symptoms: clicking any feature in the Feature List or Feature Card throws:

The Anchor Table does not exist. Identification fields and values: Table No.='<number>'

The error occurs for all features, not just the one tied to that table. The referenced table exists in the environment, symbols are up to date, and the SOD Setup General tab matches the source environment. The table may also be missing from SOD's own Tables list although it exists in Business Central. Download Source produces the same error.

Context: observed after using Import App to move an SOD project into a fresh sandbox. The internal table metadata used by the feature routine (RefreshTableMetaWithFeaturesAndNewFields) is missing or stale in the new environment.

Resolution: update SOD to the latest AppSource version via Admin Center / Extension Management, then reopen the features. The issue was present in 12.0.0.664 and resolved in 12.0.0.667.

Limitation: clicking Download Source to force a metadata rebuild does not help — it produces the same error. There is no user-facing "rebuild table metadata" action that clears this condition.

After a Business Central Update

Objects Showing as Missing After BC Update

Symptoms:

  • Objects that previously worked now show as missing
  • After BC platform update
  • Validation errors on existing customizations

Causes:

  • BC update changed object IDs or structures
  • Symbol cache is outdated
  • Extension updated with breaking changes

Solutions:

  1. Re-download symbols with the cache cleared
    • Always do this after BC updates: Setup > Refresh Symbols > answer Yes to clear the cache
  2. Review customizations
    • Check if referenced objects still exist
    • Update placements if objects were renamed/removed
  3. Then republish — the extension in the environment is unchanged until you do

See Business Central Updates and Compatibility for the error-by-error guide.

Query APIs Losing Columns After a BC Update

After a platform update — even a minor version increment such as 25.4 to 25.5 — previously working SOD query APIs may stop returning some columns, and consumers such as Power BI report missing fields.

  1. First step: re-download symbols (Setup > Refresh Symbols).
  2. Then check which entity the error actually names. The consumer's error may reference a different table from the query source table you are editing — an invoice header or consolidated invoice header entity, for example, when you are looking at a sales header query. Match the error to the correct query before changing anything.

Stale Field Metadata After an Extension Update

Symptom: after updating a third-party extension and refreshing symbols, publishing still fails with:

'Record "<Table Name>"' does not contain a definition for '<Field Name>'

pointing at a generated file such as src/API/<name>.APIPage.al.

Cause: the symbol cache still holds metadata for a field that was removed or renamed in the updated extension. A plain refresh does not always replace it.

Steps:

  1. Refresh Symbols with cache clearing — a refresh without clearing is not enough here
  2. Verify the field actually still exists on the source page/table. A field that no longer exists in the environment cannot be included in the generated API — exclude it from your configuration
  3. If it persists, Download Source, rename the ZIP to .txt, and email it to support@hougaard.com

Generated Extension Missing After a BC Update

Symptom: after a Business Central update, your generated customization extension is gone entirely from Extension Management — not even listed as uninstalled.

Cause: this can happen when a dependency app is removed during the upgrade.

Reassurance: data is not lost. The customization definitions remain intact inside SOD, so republishing regenerates and redeploys the extension.

Recovery:

  1. Open SOD and go to the Setup page
  2. Refresh Symbols, answering Yes to clear the cache
  3. Publish the app again

Dependency Issues

Stale Dependency Information

When a publish fails with a circular or missing dependency error that names apps whose current configuration shows no such dependency, the symbol cache may be holding outdated dependency information.

Refreshing symbols with the cache cleared resolves these stale-dependency failures. Try it early whenever a dependency-related publishing error appears.

Extra / Unwanted Extension Dependencies

To reduce inherited dependencies at build time:

  1. Re-download symbols in the environment where you build and publish, so the cache matches what is actually installed there
  2. If an unneeded extension is installed in that build environment and can be uninstalled, consider uninstalling it
  3. Publish again to generate a new .app, then install it in the target environment

Caveat: this only removes dependencies that are not genuinely required through the dependency chain. If an upstream dependency legitimately requires the extension, refreshing symbols will not remove it. See Circular Dependencies.

Dependencies Not Detected When Updating Symbols

Symptom: a required dependency is not added automatically when symbols are updated, so the generated app cannot find fields from that extension. Downloading the source and manually adding the dependency to app.json makes it compile — confirming the dependency is valid but was not detected.

Related indicator: the app version may appear blank on the "Extension Installation Status Detail" page.

Known issue: a defect in SOD prevented some dependencies from being detected. It was fixed through a platform-side app update, not solely by upgrading the SOD extension version.

Steps:

  1. Update SOD to the latest version in the Admin Center (environment > Apps)
  2. If the problem persists on the latest version, contact support — a server-side update may be required

Symptoms:

  • Download fails with license error
  • "User doesn't have valid license" message

Causes:

  • BC license doesn't include required functionality
  • License type restrictions
  • Trial license limitations

Solutions:

  1. Verify BC license
    • Check that your user has a valid BC license
    • Confirm license includes development capabilities
  2. Check SOD license
    • Verify SOD license is active
    • Expired SOD license may affect functionality

Diagnostic Steps

When troubleshooting any symbol issue:

Step 1: Note the Error

  • Write down the exact error message
  • Note when it occurs in the process
  • Screenshot if possible

Step 2: Check Environment

  • Sandbox or Production?
  • What BC version?
  • What SOD version?
  • Does the same operation work in a sandbox? (Different symbol source — a working sandbox does not rule out a production outage)

Step 3: Verify Permissions

  • Review your permission sets
  • Confirm they are assigned with no specific company
  • Check with administrator if needed

Step 4: Try Basic Fixes

  • Refresh Symbols from the Setup page with cache clearing
  • Confirm Allow HttpClient Requests is enabled
  • Clear browser cache, try a different browser
  • Retry the operation — downloads resume where they left off

Step 5: Contact Support

If issue persists:

  • Document all troubleshooting steps taken
  • Include error messages and screenshots
  • Use Download Source on the Setup page to export the generated code as a ZIP; rename it to .txt and email it to support@hougaard.com

Getting Help

If you cannot resolve the issue:

  1. Documentation - Check hougaard.com/designer for updated guides
  2. Support Forum - Post in the support forum
  3. Direct Support - Contact Hougaard support with details

When the cause is a Microsoft outage, the resolution is on Microsoft's side and Hougaard cannot fix it directly. Raise a ticket with Microsoft — normally through your Business Central partner — including the failing request path and the returned GatewayTimeout code as diagnostic detail. Use a sandbox to keep working meanwhile.