Troubleshooting a Portal

Overview

If you experience an issue in a published portal, you may need guidance on what to do next.

This page provides information on where you should look first when diagnosing a problem along with some of the most common errors in portals and how to resolve them.

Identifying issues in your portal

During development

Logs are the primary way to identify and troubleshoot issues in your portal during development.

Logs

Because portal-related errors can come from a variety of sources, one of the best places to look when trying to pinpoint the origin of a problem during development is the portal error logs.

Start by looking at the error message to see what may be causing the error. From there, you can determine the best place to look for more information.

For example, the issue causing an error may be a connected system. You can use the portal error log to find out which connected system is causing the error and then test and troubleshoot the connection accordingly.

If the error is about connecting back to Appian, integrations, databases, or APIs, check out the server log for your environment, external system, or database.

If you don't have admin access to the portal error log or they aren't available in your environment, you can check the portal server log in the portal object.

In addition to the errors and portal server logs, you can find issues and information for portal processes, actions, and key usage and performance metrics in the following places:

• Your environment server log.
• Portals latency, traffic, and error rate metric log.
• Portals rule performance details logs.
• Your external system or database server log.

In production

Once your portal is live, the Portal Monitoring tab in the Monitor View is the best way to understand how users are experiencing your portal. Email error alerts will notify users with Administrator permissions and provide a link to the portal object.

Portal monitoring

The Portal Monitoring tab allows you to view key metrics and details that are vital to understanding how users are interacting with your portals and what issues they may be experiencing. Regularly monitoring these metrics alerts you to any potential issues related to response times or availability and helps ensure you aren't serving slow or inaccessible portals to your users. To view metrics for your production environment, use the icon to switch from one environment to another.

Email error alerts

If a portal user encounters an error in a published portal, an email alert is sent with details about the error.

These email alerts are automatically sent to users with Administrator permissions to the portal object. Each environment can have different users with these permissions.

Email alerts will display:

• Problem - the first sentence of the error message along with the error code if applicable.
• When - date and time the error occurred.
• Details - the rest of the error message.
• Recommended Action - suggestions to troubleshoot the error.
• A link to the portal object.

To start troubleshooting, try to reproduce the error in your published portal. This will give you an idea of where you should look next. For example, the object causing the error could be an interface or integration. You can use the error details in the email alert to help you pinpoint the problem in the object.

You can also check the portal server log in the portal object or the portal error logs in the relevant environment. See the logs section for more information.

Common errors

Error Message	Cause/Next Steps
[title=Connection failed, message=Could not authenticate with the connected system or connect to the external system at the specified URL, detail=HTTP/1.1 404 Not Found] For integrations that don't use connected systems: [title=The requested URL cannot be found, message=The external system did not find the requested URL or is refusing to allow access, detail=HTTP/1.1 404 Not Found] More information about this error can be found in the activity log which you can download from the portal object. There are two different ways to view this error: - If the integration queries info (GET), then the error will be available in the error field of the dictionary returned. - If the integration modifies data (POST), then the error can be accessed by fv!error in the onError parameter of the integration rule.	Cause: Incorrect API key or credentials in the connected system, or invalid URL for web API. Next Steps: 1. If you're in a development environment, check your connected system to make sure your credentials are correct by clicking the TEST CONNECTION button in the connected system object. If you're in a staging or production environment, make sure that the credentials or API keys listed in the import customization file that you used for deployment are correct and have permission to your Appian web API. 2. Ensure that the integration used by your interface can connect to the Appian web API.
File upload authentication failed. No service account was found. A service account is required to upload files.	Cause: Missing or incorrect service account for file upload. Next Steps: Check that the service account used when publishing your portal has permission to upload documents to the target document folder.
Expression evaluation error at function a!queryEntity [line 21]: Connection to the data store entity failed. The connected system data source was not found at the specified URL or is refusing to allow access.	Cause: Scenarios such as invalid database/data store entity, wrong credentials in the import customization file, or data store entity not verified. Next Steps: 1. Check that the data source is configured correctly and can be connected to from the interface. 2. If you're in a development environment, check your objects to make sure that they are using the correct credentials or API keys. If you're in a staging or production environment, make sure that the credentials or API keys listed in the import customization file that you used for deployment are correct and able to authenticate to the data source connected system.
Varies based on function or component used. Example: Expression evaluation error at function a!userRecordLink: Invalid function a!recordlink (not available as [])	Cause: The parent interface or child objects use incompatible functions or components. Next Steps: Ensure all functions and components used in the interface are compatible with Appian Portals and that partially compatible functions are connected using an integration and web API.
HTTP Code: 404 Could not find portal interface with uuid: _a-0000e827-7a29-8000-9bd3-011c48011c48_11234	Cause: A precedent of the portal has been deleted or is missing from this environment. All interface precedents must be included in the environment that is being used to publish the portal. Next Steps: Ensure there are no missing precedents of the portal in the current environment.
Varies depending on error from Google. Example: reCAPTCHA connection failed. Check that proper credentials have been provided in the reCAPTCHA connected system and test the connection.	Cause: Issue with reCAPTCHA. Next Steps: See Testing, monitoring, and troubleshooting reCAPTCHA for more information. 1. Ensure that the reCAPTCHA Site key, API key, and Project ID are correct in the portal object. 2. Ensure that your Google project is set up correctly to use reCAPTCHA.

Feedback