App Builder troubleshooting

This guide covers common errors and issues encountered when installing, configuring, and using Jitterbit App Builder. Start with the diagnostic steps below, then find your specific issue in the relevant section.

For a unified reference covering integration, automation, API management, EDI, and app development issues in one place, see the Harmony troubleshooting guide.

Diagnostic steps

Check your build against the release notes

App Builder is delivered as discrete on-premises releases (App Builder 4.0 and later; the 3.x and earlier line was branded Vinyl, whose documentation is maintained separately), and each release folds in accumulated fixes. A symptom you are chasing may already be resolved in a newer build, so note the build you are running and scan the App Builder release notes for a corresponding fix before investigating further. Upgrading to the newest available release is the quickest way to rule that out.

Determine whether the error is client-side or server-side

Client-side and server-side errors are diagnosed in different places, and only server-side errors reach the App Builder logs:

• Server-side errors occur in App Builder itself and are almost always recorded in the application logs. You can retrieve the details later even if the user did not copy the message when it appeared.
• Client-side errors occur in the browser on the user's own computer and are not recorded by App Builder. To see the detail, open the browser's developer tools (F12 in Chrome or Edge) and check the Console panel while reproducing the error.

An error that reports a Url value and references a JavaScript (.js) file is client-side. Common causes are the design of the page, an issue in the app template or a widget, or a slow or interrupted network connection.

The browser's Network panel also shows the HTTP status code returned for each request, which distinguishes a client error (for example, 401 or 404) from a server error (for example, 500 or 504). See Identify HTTP error codes.

Check the application logs

App Builder records logs both in-product and as files on the server. From IDE > Monitoring, you can view several log types, each suited to a different kind of problem:

• Database Logs and Memory Logs: Application error and event entries, including stack traces. Start here for most errors. Entries are ordered by LogId, so sort in descending order to bring the most recent error to the top.
• Event Logs and System Events: Background event and system-level activity.

To capture more detail, select a log entry, click Edit Configuration, and raise the log verbosity (for example, to Trace). To also include the application data that App Builder normally masks in logs, enable Log Secure Data; see Log secure data.

From the same dialog, use Download Disk Logs to download the disk logs from all servers in the environment. The files are also written to the logs directory under the App Builder installation root. For all Monitoring options, see IDE Monitoring page.

Enable CData data server logging

Many App Builder connectors are CData-based. If an issue involves one of these data servers, enable logging for it and download the log file to inspect the connector-level detail. See Enable CData data server logging.

Check session, page view, and REST logs

Depending on the problem, other logs may be more useful than the application logs:

• Session and page view logs: Session logs help with authentication, authorization, and identity issues; page view logs show which pages a user visited. See Page view and session activity logging.
• Sessions tab: From Monitoring > Sessions, see who is currently signed in, each session's last activity, and page view counts.
• REST logs: Troubleshoot inbound and outbound API calls and webhooks. See Configure REST logging.

Copy error messages from the UI

When an error message appears in the App Builder UI, use the Copy button within the error region to copy the full error text to your clipboard. Paste it into a text editor or a support case for easier review. In the copied log, scroll to the exception data, usually the most descriptive part and often enough to resolve the error yourself. If Log Secure Data is enabled, the SQL query metadata appears below it.

Diagnose network connectivity issues

Connection failures occur on one of two paths: from a user's browser to the App Builder server, or from the App Builder server to another server such as a database, an API, or an SMTP host. Run these commands from the machine at the start of the failing path, so that a test from the App Builder server is run on that server rather than on a workstation:

• telnet <hostname> <port> or, in PowerShell, Test-NetConnection <hostname> -Port <port>: confirms that a TCP connection to the port can be opened. A failure points to a firewall rule, an incorrect port, or a service that is not listening.
• nslookup <hostname>: confirms the hostname resolves to the expected address.
• ping <hostname> and tracert <hostname>: show whether the host is reachable and the route taken, on networks that permit ICMP traffic.
• ipconfig /displaydns: lists cached DNS entries, which is useful after a DNS record has changed.

Frequent causes of connection failures include an incorrect hostname or port, DNS resolution, a firewall or allowlist that omits some of the remote service's IP addresses (some services publish a large range), IIS configuration, and an overloaded or misconfigured server between the two endpoints.

Capture a HAR file

A HAR (HTTP Archive) file records every network request a browser made while a page was loading or an action was performed. It is useful when a page loads slowly, never finishes loading, or fails without producing a logged error, and Jitterbit support may ask you to provide one. For the procedure, see Generate a .har file.

Retrieve a process dump

If App Builder is slow to respond or unresponsive, retrieving a process dump from the w3wp.exe IIS worker process can help support diagnose the cause. See Retrieve a dump file for instructions.

Installation and startup

App Builder fails to start with a 500 error

• Symptom: App Builder fails to start on IIS and returns an HTTP 500 error.
• Possible cause: The ASP.NET Core Runtime Hosting Bundle that App Builder requires is not installed on the Windows server, so IIS cannot start the application.
• Resolution:
  1. Install the ASP.NET Core Runtime Hosting Bundle required by App Builder, as listed in the System requirements.
  2. Restart IIS and verify that App Builder loads correctly.

App Builder fails to start with an HTTP 500.30 error

• Symptom: App Builder fails to start and returns:

  HTTP Error 500.30 - ASP.NET Core app failed to start
  

• Possible cause: The IIS application pool identity does not have full access to the App Builder root folder, so the application cannot start.

• Resolution:

  1. Grant the App Builder application pool identity (by default, IIS AppPool\Vinyl) Full control of the App Builder root folder. See Set permissions.
  2. Restart the application pool, then reload App Builder.

App Builder returns an HTTP 503 error

• Symptom: Opening App Builder returns:

  HTTP Error 503. The service is unavailable.
  

• Possible cause: The IIS application pool for App Builder is stopped.

• Resolution:

  1. Open IIS Manager and select Application Pools.
  2. Select the App Builder application pool (by default, Vinyl), then select Start.

  Note

  If the application pool stops again immediately after starting, App Builder is likely failing on startup. Review the application logs and the Windows Event Viewer for the underlying error.

App Builder starts but does not create databases

• Symptom: App Builder starts successfully but no databases are created on the SQL Server.
• Possible cause: The connection file has an incorrect extension (for example, .txt instead of .xml).
• Resolution: Locate the App Builder connection file and confirm it uses the .xml extension. Rename the file if the extension is incorrect, then restart App Builder. If App Builder starts but returns a connection error rather than silently creating no databases, see An error occurs loading the database connection information.

An error occurs loading the database connection information

• Symptom: App Builder returns the following error:

  An error occurred while attempting to load the database connection information.
  

• Possible cause: The Connection.xml file is missing or contains incorrect connection data.

• Resolution:

  • Replace or update Connection.xml with the correct connection data, then restart App Builder. See Create a connection file.
  • If App Builder starts without an error but creates no databases, see App Builder starts but does not create databases.

App Builder loads with missing or broken styling

• Symptom: App Builder starts, but pages render with missing or broken styling (CSS).
• Possible cause: The installation ZIP was not unblocked before it was extracted. Windows flags files downloaded from another computer as blocked (the "mark of the web"), and extracting a still-blocked archive propagates that mark to the extracted files, which can prevent App Builder's style assets from loading correctly.
• Resolution:
  1. Delete the extracted files.
  2. Unblock the original ZIP file: right-click it, select Properties, open the Security tab, and select Unblock. See Get and unpack the software.
  3. Extract the ZIP again, then restart the installation or upgrade.

License upload fails

• Symptom: Uploading a license file fails with one of the following errors:

  An unknown error occurred.
  

  405 POST Method not allowed
  

  Failed to deserialize license (d3fc6d4e835e)
  

• Possible cause: WebDAV is installed or enabled on IIS and can interfere with the POST request used to upload the license.

• Resolution:
  1. Uninstall or disable the WebDAV module in IIS.
  2. Retry the license upload.
  3. If WebDAV is required for other applications on the server, contact Jitterbit support for guidance on configuring both services to coexist.

App Builder does not auto-start after a server restart

• Symptom: App Builder does not automatically become available after the Windows server restarts, requiring a manual first request to initialize the application.
• Resolution: For resolution steps, see Troubleshoot auto start behavior.

Docker deployment: App Builder 4.x license cannot be uploaded in the UI

• Symptom: After upgrading from Vinyl 3.3 to App Builder 4.x on Docker, uploading the App Builder license through the App Builder UI fails or the option is unavailable.
• Possible cause: App Builder 4.x Docker deployments do not support license upload through the UI.
• Resolution: Provide the license through one of the following methods:
  • In the docker-compose.yml file, set the License__LicenseKey environment variable to the base64-encoded App Builder 4.x license key.
  • Add the license key to the appsettings.json file in the data subdirectory of the Docker compose directory.

High availability: All instances must use the same appsettings.json

• Symptom: In a high availability deployment, some App Builder nodes behave differently from others (for example, authentication works on some nodes but not others, or data encryption keys are inconsistent across nodes).
• Possible cause: Every instance of App Builder in a high availability deployment must use an identical appsettings.json configuration file. If the files differ between instances, behavior will be inconsistent across nodes.
• Resolution:
  • Confirm all App Builder instances in the HA deployment have identical appsettings.json files.
  • After changing configuration on one instance, apply the same change to all other instances and restart each one.

Authentication failures

SSO login fails or redirects to the wrong URL

• Symptom: Users attempting to log in via single sign-on (SSO) encounter a redirect error or are sent to an unexpected URL.
• Possible causes:
  • The Redirect URI configured in the Identity Provider (IdP) does not match the URL App Builder is using.
  • A reverse proxy or load balancer in front of App Builder (for example, IIS behind an F5) terminates TLS, so App Builder sees http while the public URL uses https. The Redirect URI then uses the wrong protocol and does not match the value registered in the IdP.
  • The SSO integration URL in App Builder references an outdated or incorrect address.
  • The OpenID Connect security provider in App Builder is misconfigured.
• Resolution:
  • In the IdP (for example, Okta or Azure AD), confirm the Redirect URI matches the App Builder application URL exactly, including the protocol (https://) and any path.
  • In App Builder, review the security provider configuration in IDE > Security Providers and verify the OpenID Connect settings match the IdP's expected values.
  • If the App Builder URL has changed (for example, after a migration or domain update), update the Redirect URI in both App Builder and the IdP.

The base URL does not redirect to the login page

• Symptom: Opening the base URL of an App Builder environment (for example, https://example.com/) does not redirect to the login page. Unauthenticated visitors are taken directly to an app instead.
• Possible cause: The built-in anonymous user has access to an app's home page. App Builder automatically redirects each user to a home page they can access, so when the anonymous user can reach an app's home page, all unauthenticated visitors are redirected there instead of to the login page.
• Resolution: Remove the anonymous user's access to the app's home page so that unauthenticated visitors are directed to the login page.

Local users cannot reset a forgotten password

• Symptom: Local users are unable to reset a forgotten password. The Forgot Password link on the login screen is missing or does not complete the reset.
• Possible cause: The Anonymous Users group has not been granted access to the password reset application, so unauthenticated users cannot reach the password reset workflow.
• Resolution: Grant the Anonymous Users group access to the App Builder - Password Reset application and add it to the Password Reset role. See Password reset for the full configuration steps, including the required SMTP setup.

Salesforce OAuth authentication fails or authenticates with the wrong instance

• Symptom: Users logging in with Salesforce SSO are unexpectedly authenticated with the wrong Salesforce instance, or Salesforce tokens stop working and users are prompted to re-authenticate repeatedly.
• Possible causes:
  • Multiple App Builder instances share the same Salesforce Connected App. Salesforce retains only the four most recent refresh tokens per Connected App. When a fifth token is issued, the oldest is invalidated, causing the instance holding that token to lose authentication.
  • Multiple Salesforce instances are configured in App Builder, and the user's browser already has an active session with one Salesforce instance. When the user attempts to log into a second instance, Salesforce re-uses the existing session and logs the user into the first instance instead.
• Resolution:
  • Assign a separate Salesforce Connected App to each App Builder instance to prevent refresh token conflicts. See the Salesforce security provider documentation for configuration details.
  • If a user is being authenticated with the wrong Salesforce instance, have the user sign out of all active Salesforce sessions in their browser before attempting to log in again.

Performance

App Builder is slow or unresponsive

• Symptom: App Builder responds slowly to user interactions, or page loads and queries time out.
• Possible causes:
  • The App Builder server has insufficient CPU or memory resources for the current load.
  • A network issue between the user and the App Builder server, such as limited bandwidth, packet loss, or a firewall, is slowing data transmission.
  • Unoptimized queries or application logic are producing slow pages, or a background service is consuming excessive resources.
  • The IIS worker process has entered an unhealthy state.
  • A long-running operation exceeded the timeout of a proxy, load balancer, or other network device between the browser and App Builder, which then disconnected the browser. The browser reports an error such as 504 Gateway Timeout, but the operation continues to run on the server and can still succeed or fail after the browser is disconnected.
• Resolution:
  • Review server resource utilization (CPU, memory, disk I/O) to identify any resource saturation.
  • To rule out a network issue, connect from a different network (for example, another Wi-Fi network, or a mobile device on a cellular connection) and run an internet speed test. If performance improves on another network, the cause is likely limited bandwidth, an ISP issue, or a firewall rather than App Builder itself.
  • Check the application logs for recurring errors, timeouts, or warnings that may indicate the cause.
  • If the browser reported a gateway timeout, use the event history to determine whether the operation finished on the server before you retry it. Because the operation keeps running after the browser is disconnected, retrying it can duplicate the work.
  • Review active background services and event history for any long-running or stuck jobs. To identify slow SQL queries specifically, see Capture and analyze slow queries.
  • For slow pages caused by unoptimized queries or application logic, see App Builder performance tuning for query optimization, indexing, and application design guidance.
  • If the server appears healthy but App Builder remains unresponsive, recycle the IIS application pool for App Builder.
  • If the issue is intermittent and difficult to diagnose, retrieve a process dump for further analysis. See Retrieve a dump file.

Data and integrations

Encrypted column values appear blank after data source reconfiguration

• Symptom: Values stored in an encrypted column appear blank (null) in the application after a data source, table, or column was deleted and recreated, or after upgrading or migrating the App Builder environment.
• Possible causes:
  • App Builder derives each column's encryption key from the DataSourceId, TableId, and ColumnId values in its logical model. If any of these identifiers change (for example, after deleting and recreating a data source, table, or column), existing encrypted values can no longer be decrypted. No error is displayed: the value silently appears as null.
  • During an upgrade or migration, the keys folder from the previous installation was not copied to the new installation folder, so App Builder cannot access the key material needed to decrypt existing values.
• Resolution:
  • If encrypted values appear blank after an upgrade or migration, confirm that the contents of the keys folder were copied from the previous installation folder to the new one. See step 5 of Restore settings.
  • To prevent data loss from identifier changes, avoid deleting and recreating data sources, tables, or encrypted columns that contain data. For a complete list of encryption limitations, see Application-level column encryption.
  • Before making structural changes, export or back up any encrypted column values.
  • If the identifiers have already changed and the data cannot be recovered from a backup, contact Jitterbit support with details of the original configuration.

Audit log baseline fails to populate

• Symptom: Populating the Full Audit baseline throws an error and the baseline is not created.
• Possible cause: The table does not have a single-part UUID primary key. Full Audit requires a unique UUID for each record, so tables with a composite (multi-part) primary key are not audited by default. To audit such a table, you must first add a UUID audit column.
• Resolution:
  1. Add a UUID column to the table and set its column usage type to Audit, then populate it for existing records. For the full procedure, see Other primary key configurations.
  2. Navigate to Action Drawer > IDE > Additional Settings and click the Populate Audit Records button.
  3. Locate the app's data source, click Populate All (or Populate on individual tables), then click Proceed to retry.

SharePoint File System: OAuth authentication required as of April 2026

• Symptom: SharePoint File System connections fail to authenticate or cannot be created.
• Possible cause: As of April 30, 2026, SharePoint File System connections require OAuth authentication. Connections using legacy authentication no longer work.
• Resolution:
  1. Upgrade to App Builder 4.61 or later.
  2. Follow the Microsoft SharePoint OAuth connection guide to configure an OAuth security provider before creating or updating the data server.

SharePoint File System: Files not displayed or paths return errors

• Symptom: A SharePoint File System data source is connected successfully but files are not displayed, content does not render, or a directory path causes an error.
• Possible causes:
  • App Builder can only access files stored in the Documents directory. Files in other SharePoint directories are not accessible.
  • File names are case-sensitive when binding between data sources. A casing mismatch between the SharePoint file name and the name used in another data source prevents content from rendering.
  • Using a forward slash (/) in a directory path in a business object causes an error.
• Resolution:
  • Confirm the files are stored under the Documents directory in SharePoint.
  • Verify that file names used in business objects and data source bindings exactly match the casing of the SharePoint file names.
  • When specifying a directory path in a business object, use backslashes (\\) instead of forward slashes (/). For example, use \documents\employees instead of /documents/employees.

App Builder Connector: Generated API key cannot be retrieved after leaving the screen

• Symptom: A connector user has set up the App Builder Connector but the API key value is no longer available after navigating away from the key generation screen.
• Possible cause: The generated API key is displayed only once on the Generate Key screen. Once you leave the screen, the value cannot be retrieved.
• Resolution:
  • Copy the key value to the clipboard immediately after it is generated, before navigating away.
  • If the key was not copied, generate a new key.

App Builder Connector: 403 Forbidden error

• Symptom: Connecting to a remote App Builder environment using the App Builder Connector returns a 403 Forbidden error.
• Possible cause: The user account configured for the connector has not been granted the App Builder Remote Connector role in the source App Builder environment.
• Resolution:
  1. In the source App Builder environment, open the user account used by the connector.
  2. Assign the App Builder Remote Connector role to that user.

Webhook: HTTP Basic Auth requires the Authorization header in the payload

• Symptom: A webhook configured to use HTTP Basic Auth does not process incoming payloads correctly.
• Possible cause: The HTTP Basic Auth method requires the Authorization header to be present in the received payload. Third-party systems that omit this header do not authenticate correctly.
• Resolution: Use the API Key authentication method for the webhook security provider instead of HTTP Basic Auth. The API Key method does not require the Authorization header and is more broadly compatible with external webhook senders.

Date migration times out on large datasets

• Symptom: A date migration operation does not complete and fails with a timeout error.
• Possible cause: Date migrations run as a single database transaction during an app or data source upgrade. With large datasets, the transaction may exceed the database's default command timeout.
• Resolution: In the App Builder Connection.xml file, increase the CommandTimeOut value to allow more time for the migration transaction to complete.

Time zone configuration

App Builder application server and database server must use the same time zone

• Symptom: DateTime values in the application are shifted by unexpected offsets, or times displayed in App Builder differ from what is shown in the database.
• Possible cause: The App Builder application server and the database server are configured with different time zones. These servers must be in sync for DateTime values to render correctly.
• Resolution:
  1. Confirm the App Builder application server and all database servers are set to the same time zone.
  2. In App Builder, set the Default Data Source Time Zone on each data source server and the Time Zone on each data source to match the database server's time zone. See Time zones for configuration steps.

Email notifications

SMTP configuration errors

• Symptom: App Builder cannot send email notifications, and the application logs or the Test Email output shows one of the following errors:

  Argument passed in is not serializable. Parameter name: value
  

  Value cannot be null. ParameterName: From Address
  

  Unknown URI scheme. Parameter name: uri
  

  Authentication required
  

• Possible causes:

  • The SMTP notification server's From Address field is empty, null, or uses an invalid email address (produces the first two errors above).
  • The URI field uses an invalid format or unsupported scheme (produces the "Unknown URI scheme" error). The URI must use the smtp:// or smtps:// scheme, for example smtp://mail.example.com:587.
  • The UserName or Password fields contain incorrect credentials (produces the "Authentication required" error).

• Resolution: In the IDE, from the Connect options open Notification Servers, then open the SMTP server record and check the field that matches the error you received:

  • Verify the From Address is a valid email address permitted to send mail through the configured SMTP host.
  • Verify the URI uses the format smtp://<hostname>:<port> or smtps://<hostname>:<port>. See Configure SMTP for supported protocols and format.
  • Verify the UserName and Password match the SMTP server credentials.
  • After making a change, use the Test Email feature in the notification server popup to confirm the settings before deploying them to a workflow.

Pages and application behavior

Deep links stop working after an app or page is renamed

• Symptom: A deep link that previously directed users to a specific application or page no longer works.
• Possible cause: Renaming an application or page in App Builder changes the URL path used in deep links. Any existing link containing the old application or page name is no longer valid.
• Resolution:
  • Update any external systems, emails, portals, or bookmarks that contain the old deep link URL to use the new application or page name.
  • Construct the new deep link by navigating to the target page in App Builder and copying the URL from the browser address bar, then removing the query string (everything from ? onward) to get the canonical URL.
  • To avoid this issue in the future, use the Label field for display names and keep the Name field (which determines the URL path) short and stable.

An event fires multiple times on save, insert, update, or delete

• Symptom: An event that should fire once triggers multiple times on the same user action, resulting in duplicate records, duplicate notifications, or other repeated side effects.
• Possible causes:
  • The event's action or validation is registered in both the data layer and the business logic layer simultaneously. App Builder allows this configuration, but fires the event once per layer registration.
  • The action's binding is unbound, or is bound to more than one record. The action fires once for each record in scope.
• Resolution: Open the App Workbench, locate the event's configuration, then address the cause that applies:
  • Determine whether the logic belongs on the data layer (for table-wide behavior) or the business logic layer (for page-specific behavior). See Configure events for guidance, and remove the duplicate registration from whichever layer it does not belong on.
  • Review the action's binding. If it is unbound or bound to more than one record, scope it to the single intended record. See Implicit and explicit binding.

HTML icon controls do not respect role permissions

• Symptom: An HTML icon control on a page does not respect a user's role permissions. For example, an icon that should be disabled for users without permission remains active.
• Possible cause: HTML icons behave like buttons. Without an event attached, role-based permissions do not apply to the icon, so it stays visible and active regardless of the user's role.
• Resolution:
  1. Attach an empty event to the HTML icon control so that role-based visibility applies.
  2. Specify the appropriate access (for example, Update) in the role for the users who should see the icon.

Audit icon does not appear on a page

• Symptom: The Audit button or icon used to view Full Audit logs is not visible on a Form or Grid panel.
• Possible causes:
  • The user does not belong to the App Builder - Administrators role or the App Builder - Audit role.
  • The page panel does not have Show Audit enabled, or the panel is not a Form or Grid panel.
• Resolution:
  • Confirm the user belongs to the App Builder - Administrators role or the App Builder - Audit role. See Security.
  • On a Form or Grid panel, enable Show Audit for the page panel. See Enable full audit on a page.

Mobile and offline apps

For issues with the App Builder mobile app (including freezes, crashes, blocked links, and image-saving problems), see Mobile app troubleshooting.

Offline app: Local database is erased when the app is upgraded

• Symptom: After an offline app is upgraded, all locally stored data on the mobile device is gone.
• Possible cause: An offline app's local database is erased whenever the app is upgraded. This is a known limitation of offline apps.
• Resolution:
  • Ensure that all locally collected data is fully synchronized to the server before an app upgrade is deployed.
  • Inform users of planned upgrades in advance so they can sync before the upgrade takes effect.

Offline app: Background schedules do not run when the app is closed

• Symptom: Scheduled tasks or background processes in an offline app are not executing on a mobile device when expected.
• Possible cause: Background schedules do not run when the App Builder app is closed on the mobile device. Schedules only execute while the app is open.
• Resolution:
  • Inform users that scheduled background processing requires the app to remain open.
  • Redesign workflows that depend on background schedules to trigger on user interaction, or move the scheduled processing to the server side.

Widgets

For issues with widgets not activating, loading incorrectly, or failing to read a widget zip file, see Widget troubleshooting.