troubleshooting-ae1d53e.md

Troubleshooting

A troubleshooting guide for HTML5 application repository.

Uploading Applications

400: Application metadata already exists when uploading HTML5 applications

Term	Description
Issue	HTML5 Application Deployment fails with error "Application metadata for application xyz already exists."
Cause	There is already an app-host service instance that contains a manifest.json with app.id = xyz in this space it is not possible to have multiple app-hosts containing the same app.id.
Solution	Delete or do not deploy the old app-host instance or use another app.id in the resources folder for a new app-host.

400: Failed to run the application router after subscription; route not found

Term	Description
Issue	After subscribing to the application router using the <subdomain>-<myapprouter>.<scp domain> format, the calling the application router fails with error "route not found".
Cause	In order to support subscriptions out of the box, a route with format *.<custom-domain> should be created and mapped to the application router. The * host represents a wildcard that is replaced by the actual subscriber subdomain during runtime. Without a custom domain, this type of route (wildcard host) cannot be created; only a fixed host can be used. Without a custom domain, the route format is <subdomain>-<myapprouter>.<scp domain>. It means that you have to create a route with the expected subdomain for each new subscriber.
Solution	In development setups, if you don't have a custom domain before subscription, then create a route with the expected subscriber subdomain.

400: Uploading application content failed

Term	Description
Issue	When trying to upload content, it fails with error: "Upload failed".
Cause	One or more of the input validations performed by HTML5 application repository failed. The possible validation failures are: Missing manifest.json file on the root level. manifest.json app.id has invalid characters (hyphens, @, %, &, etc.). manifest.json app.version is not using the following format: xx.xx.xx, where x must be an integer (e.g.: -snapshot is not supported). app.id of one or more of the applications already exists in another html5-apps-repo/app-host service instance in the same space.
Solution	Check if one of the causes is your issue. For example, check the size of your html5-app-deployer resources folder, check manifest.json. If you are not sure if another service instance already uses your app.id, try making a small change to your app.id and deploy it again.

403: App-host is being modified by another process

Term	Description
Issue	HTML5 application repository deployment fails with error "app-host is being modified by another process."
Cause	The HTML5 application repository deployer attempts to upload content while another deployer is also uploading content using the same app-host.
Solution	Try again after the first HTML5 application repository deployer has completed its upload.

409: App-host deploy or redeploy remains in progress

Term	Description
Issue	HTML5 application repository deployment fails with error "Deploy in progress" or "Redeploy in progress" and response type 409 for a long time or any other issue.
Cause	If something happens during the upload, it might cause some inconsistencies.
Solution	Delete the content of one or more multiple app-hosts, and reset the state to initial without deleting the service instances. Use the following command line in the CF CLI HTML5 application repository plug-in: cf html5-delete --content <app-host-id> [...]

Failed to upload content; exceeded maximum file length

Term	Description
Issue	When trying to upload content, it fails with error: "Error while parsing request; Error: maximum file length exceeded".
Cause	The zipped application file length exceeds the size limit of the app-host service instance.
Solution	Increase the app-host size limit using the update service. For example: cf update-service my-app-host -c '{"sizeLimit":100}'.

Timeout while uploading content

Term	Description
Issue	When trying to upload content using the cf push command, it fails with error: "Failed to make TCP connection to port 8080: connection refused. Timed out after 1m0s: health check never passed."
Cause	The cf push plugin checks if the start process is finished. If the process times out, then it tries to start it again.
Solution	Set health-check-type to none in the manifest.yaml of the HTML5 Application Deployer.

Uploading application content failed; application size exceeds the maximum size limit of 100 MB

Term	Description
Issue	When trying to upload content, you receive the following error: "Uploading application content failed: application's size exceeds the maximum size limit of 100 MB".
Cause	The unzipped applications content exceeds the size limit (deprecated) of the app-host service instance.
Solution	Deploy an application that is less than 100 MB or remove some of your applications and move them to another app-host. .

Running Applications

400: Failed to retrieve xs-app.json; invalid app-host ID

Term	Description
Issue	Serving content from the HTML5 application repository fails with error "Invalid App Host ID. Please check with business service provider if the requested App Host ID is valid".
Caution	HTML5 application repository belongs to a business service and the app host ID is invalid or incompatible.
Solution	Ask the business service owner to define"public" : true in the app manifest.json or wait until the HTML5 application repository is restarted.

403: Failed to retrieve xs-app.json; unauthorized

Term	Description
Issue	Serving content from the application router fails with error "Unauthorized. Please check with the business service UI provider if the requested UI is defined as public".
Cause	HTML5 application repository belongs to a business service and it is not public.
Solution	Ask the business service owner to define "public": true in the app manifest.json.

404: Application does not exist

Term	Description
Issue	The HTML5 application repository fails to serve content. The application log states: "Application xyz does not exist" is printed to the console.
Cause	The application name provided in URL is not correct or the request URL doesn’t provide the application key: Application names are stored in HTML5 application repository without using full stops as separators in the URL. If manifest.json app.id equals country.list, then the application name is countrylist and the same application name should be used in URL. A request to the application router must provide the application key in the URL because the application router uses the application key to fetch the xs-app.json file of the HTML5 application from the HTML5 Application Repository. The application key can consist of the business service prefix, application name, and application version. (Only the application name is mandatory.).
Solution	First check the application name. For the request URL, use the application name without full stops as separators. If the application name is correct, check if the request URL to the application router contains the application key. If it doesn’t contain the application key, check how you configured the backend application data retrieval in your HTML5 application: If you use SAP Fiori tools such as BAS, in the manifest.json file of the application, check the dataSources.uri property. The value for dataSources.uri must not start with a slash("/"). For example, the value northwind/V2/ Northwind.svc this is correct, but /northwind/V2/ Northwind.svc/ is wrong because it would create an absolute path from which the browser cannot concatenate the application key for the request. If there is a slash, remove it. • If you use a JQueryAjax call for the request, make sure that the URL that is provided to the JQueryAjax call is a relative path and does not start with a slash ("/").

404: Calls to service endpoints specified in an application's xs-app.json fails

Term	Description
Issue	You have defined routes in a UI app's local xs-app.json but calls do not get routed and instead return a 404 error.
Cause	The routes in the xs-app.json file are processed top to bottom. If a route maps the pattern, it is picked even if a route below it is a better match. The route for the HTML5 application repository typically is a "catch all" route, and if any routes are defined below it, then they are never reached.
Solution	Move the route leading to the html5-apps-repo-rt to be the last entry in the xs-app.json file.

500: Failed to retrieve xs-app.json

Term	Description
Issue	Serving content fails with error "Error while retrieving xsApp configuration".
Cause	The HTML5 application repository is not available.
Solution	Wait until HTML5 application repository is restarted.

500: Failed to use dynamic destination

Term	Description
Issue	Serving content from the application router failed with an internal server error. In the application router application log, an error: "Destination <destinationName> is not defined as a dynamic destination in destination service, configure additional property HTML5.DynamicDestination true" appears.
Cause	The destination name provided on the host or path level is not defined as a dynamic destination in destination service.
Solution	In the additional properties section of the destination section of the SAP BTP cockpit, add the HTML5.DynamicDestination property and set the value to true.

500: Missing xs-app.json in HTML5 application repository when reading an HTML5 application file from the application router

Issue	Serving content from the application router fails with error "Application does not have xs-app.json".
Cause	xs-app.json file is missing in HTML5 Application.
Solution	Redeploy the HTML5 Application with xs-app.json file or ask the business service owner to add the xs-app.json.

Bearer token invalid

Term	Description
Issue	The app-router token exchange with a business service token fails. XSUAA returns the following error: "Bearer token invalid, requesting client does not have grant_type=user_token or no scopes were granted."
Cause	The uaa.user scope in XSUAA instance configuration is missing or the target business service is not subscribed.
Solution	If missing, add the following to the n xs-security.json file: "scopes": [ { "name": "uaa.user", "description": "UAA" }], "role-templates": [ {"name": "Token_Exchange","description": "UAA","scope-references": ["uaa.user"] } ] Redeploy or update the XSUAA service instance. Make sure that the users have the new role_template, Token_Exchange added to their role_collections in the SAP BTP cockpit Global Account > Subaccount > Security > Role Collections and verify that the created role's Application Identifier is the same as the xsappname from the xs-security.json. If the roles of the target business service does not appear on the subscriber tenant UI, it means that the target business service subscription failed or it was bound to the application router after the subscription took place. In this case, try to unsubscribe and subscribe again. Make sure that the target business service roles appear on subscriber tenant UI.

Caching issue in browser

Term	Description
Issue	Your application does not work properly after logging out and when you try to log back in, for example, click anywhere on the application screen, nothing happens.
Cause	The main page of your application, that appears after you log in, is cached by the browser. Clicking links does not reach the backend (application router) and the log in process does not work.
Solution	Check that the main page is not configured to be cached by the browser in your xs-app.json file. The best practice is to model the cacheControl as follows: { "routes": [ { "source": "^/ui/index.html", "target": "index.html", "service": "html5-apps-repo-rt", "authenticationType": "xsuaa" "cacheControl": "no-cache, no-store, must-revalidate" } ] }

Running application router after subscribing to it fails

Term	Description
Issue	After subscribing to the application router using <subdomain>-<myapprouter>.<scp domain> format, it fails and returns the following error, "route not found."
Cause	In order to support subscriptions out-of-the-box, create a route using *.<custom-domain> format and map it to the application router. The * host represents a wildcard that during runtime should be replaced by the actual subscriber sub-domain. Without a custom domain, this type of route (wildcard host) cannot be created, only a fixed host can be used. Without a custom domain, the route format will be <subdomain>-<myapprouter>.<scp domain>. It means that for each new subscriber you need to create a new route with the expected sub-domain.
Solution	If you do not have a custom domain before subscribing to the application router, create a route with the expected subscriber sub-domain.

If the lists don't not contain a solution for your issue, you can create an incident in the SAP Support Portal. For more information, see Getting Support.

Related Information

Getting Support