Troubleshooting BaaS development and runtime issues

Troubleshoot common BaaS development and runtime issues, including errors, causes, and resolutions.

Identify common BaaS issues, review their causes, and apply the appropriate resolutions.

HTTP 429 error - Too many requests

BaaS API returns HTTP 429 errors when processing high volumes of OAuth 2 token requests and notifications. This behavior causes throttling and failed calls during UAT or production load testing.

Symptoms

HTTP 429 Too Many Requests responses are returned from BaaS API. Errors typically start after approximately 300 calls in a batch. Many high-volume requests can be rejected. No issue occurs when the endpoint is called directly with an API key. The issue occurs during OAuth 2 token usage through BaaS.

Root cause

Default rate limits and Lambda concurrency limits in BaaS are too low for high-volume scenarios. API Gateway and the backend throttle excess token and notification requests, which causes HTTP 429 errors.

Solution

Increase BaaS service limits. The default maximum services per tenant is 25. Contact Support to request an update of the tenantfeature configuration for BaaS and apply the increased deployment limit value of 50 services.

Increase Lambda concurrency limits. The default maximum concurrent Lambdas per tenant is 20. Contact Support to request an update of the tenantfeature configuration for BaaS to increase concurrency to 100, with a maximum of 20 per handler.

Update the deployment configuration and redeploy the service.

Implement client-side throttling. Add retry with exponential backoff on HTTP 429 errors and limit call concurrency from the client, for example, ION.

Run load tests in UAT after the updates. Monitor for persistent HTTP 429 errors and set up alerting in the production environment.

Preventive measures

Review and adjust BaaS tenant limits regularly based on usage. Educate users about handling HTTP 429 errors with retries and concurrency controls. Update the troubleshooting knowledge base for quick reference.

Community forum link opens the Infor Concierge sign-in page

Links to the Community Forum or Known Issue can open the Infor Concierge sign-in page instead of the expected page.

Symptoms

Clicking a Community Forum or Known Issue link redirects to the Infor Concierge sign-in page.

Root cause

You are not authenticated with Infor Concierge.

Solution

Log in to Infor Concierge. In Infor Concierge Home, click Communities. This action opens community.infor.com. Retry the initial action in VS Code.

Preventive measures

Remain logged in to Infor Concierge when you access community resources.

Cannot run locally - Blob storage error

Local execution fails with blob storage connection errors.

Symptoms

There was an error performing a read operation on the Blob Storage Secret Repository. Please ensure the 'AzureWebJobsStorage' connection string is valid.

Root cause

Azurite Blob Service is not running before execution.

Solution

Start the Azurite Blob Service before execution.

Preventive measures

Ensure that Azurite Blob Service is running before you start local development.

Cannot run locally - Provider error

Local execution fails with a null parameter provider error.

Symptoms

Value cannot be null. (Parameter 'provider').

Root cause

An incompatible version of Azure Functions Core Tools is installed.

Solution

Use a different version of Azure Functions Core Tools. Run this command in a terminal:

npm i -g azure-functions-core-tools@4.0.5095 --unsafe-perm true

Preventive measures

Use the recommended Azure Functions Core Tools version for the project.

Cannot run local configuration

Run and Debug on a configuration can display an error that the configuration is not valid.

Root cause

The VS Code configuration state can become invalid after a computer restart.

Solution

Restart VS Code.

Preventive measures

Restart VS Code after a computer restart to refresh the configuration state.

Debugger not working

The debugger fails to start or does not work correctly.

Root cause

Azurite Blob Service is not running before debugger initialization.

Solution

Start the Azurite Blob Service before starting the debugger.

Preventive measures

Ensure that Azurite Blob Service is running before you start a debugging session.

Node.js cannot start local service - Function registration

Node.js service fails to start with a function registration error.

Symptoms

A function can only be registered during app startup.

Root cause

The package.json file does not contain the main field that is required from 2024.11.

Solution

Add this property to the package.json file:

"main": "dist/main.js"

Preventive measures

Ensure that framework updates configure the package.json main field correctly.

Node.js cannot start local service - Module not found

Worker cannot load a function because a required module cannot be found.

Symptoms

Worker was unable to load function ...: 'Error: Cannot find module ...'

Root cause

Incorrect module import paths are used in the code.

Solution

Ensure that relative import paths are used.

Example:

import { ... } from "generated/models/my-class"

Use this import instead:

import { ... } from "../generated/models/my-class"

Preventive measures

Use correct relative paths for all imports when you reference generated or local modules.

Error when serializing objects to XML in Java

Java serialization to XML fails.

Symptoms

MessageBodyWriter not found for media type=application/xml

Solution

See the documentation under Code Examples -> Serialization.

Compilation error in Java for missing dependencies

When a new Java project is created, the Java extension in VS Code might not resolve the new dependencies.

Solution

Restart VS Code. If the issue persists, run this command from the Command Palette:

Java: Clean Java Language Server Workspace

Cannot execute API calls locally

Symptoms

API client has not been initialized

Solution

Verify these items:

  1. The api feature is enabled in the manifest.
  2. A baas.env file exists in the root of your workspace folder. If the file does not exist, ensure that you opened the project through the workspace file and not through the folder.
  3. The Enable Local Environment setting is enabled for BaaS in VS Code settings.

Debug session exits without a message

Solution

Disable the Azure Functions: Stop Func Task Post Debug setting in VS Code.

Java project is not working in VS Code

If there are compilation problems because dependencies cannot be found, the Java Language Server might not be working.

Solution

Open the Command Palette in VS Code and run this command:

Java: Clean Java Language Server Workspace

Ensure that your JAVA_HOME environment variable points to JDK 21. Example:

C:\Program Files\Amazon Corretto\jdk21

Java project error while debugging variables

Symptoms

Cannot evaluate because of java.lang.IllegalStateException: Project ... cannot be found.

Solution

Ensure that the artifactId in the pom.xml file matches the projectName in launch.json, which is in the .vscode folder.

Open the Command Palette in VS Code and run this command:

Java: Clean Java Language Server Workspace

Cannot run locally - Security restriction

When you start the debugger and run Azure Functions on your local machine, this error can occur:

Symptoms

...You cannot run this script on the current system. For more information about running scripts and setting execution policy, see about_Execution_Policies...

Solution

Open PowerShell in administrator mode and run this command:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

BaaS extension update fails in macOS

An update of the BaaS extension can fail with this message:

Symptoms

/bin/ksh: code: not found

Root cause

Visual Studio Code.app is launched from the Downloads folder.

Solution

Move Visual Studio Code.app from the Downloads folder to the Applications folder, as described in the Microsoft installation instructions.

Launch Visual Studio Code and run this command from the Command Palette:

Shell Command: Install 'code' command from PATH

If a security error dialog appears, run the uninstall command before you run the install command again:

Shell Command: Uninstall 'code' command from PATH
Shell Command: Install 'code' command from PATH

Generating code from OpenAPI files

The OpenAPI document must define a servers property with either a URL or basePath. This property is prefixed to all generated APIs. If the property is missing, this error can occur:

Symptoms

Invalid openapi servers property. One of "url" or "basePath" variables required with prefix /api

Solution

See the REST Service section.

Java Language Server requires JDK 21 or later to start

If Java cannot be found on your system, check your JAVA_HOME system environment variable. If the issue persists, map a Java version to a path by configuring your profile setting java.configuration.runtimes.

name is the Java execution environment name and must be unique.

path must be the JDK installation directory, not the Java bin path. On Windows, escape backslashes.

Example:

"java.configuration.runtimes": [
  {
    "name": "JavaSE-21",
    "path": "C:\\Program Files\\Amazon Corretto\\jdk21"
  }
],

First deployment of the first service is not working

The first time a deployment occurs, an environment is configured behind the scenes. In some cases, the number of concurrent executions must be increased. This update can take a few hours. During this time, a message can indicate that concurrent executions are too low.

Solution

Try again after an hour.

Tenant is throttled because the rate limit is exceeded

Each customer has a daily execution time limit. When the tenant exceeds the rate limit, the tenant is throttled and all services are disabled. The available execution time is controlled by the BaaS license. See Usage limits for more information.

Solution

Try again the next day, when the tenant execution time is reset.

Upgrade the BaaS license to increase the daily execution time.

Failed to load API definition in Swagger UI

If Swagger UI fails to load the API definition, the tenant rate limit might have been reached.

Solution

See Tenant is throttled because the rate limit is exceeded .

Getting 403 Forbidden when accessing a REST API

If the REST call returns a 403 response with this message, the tenant rate limit has been reached:

Symptoms

The role definition for the function cannot be assumed by Lambda.

Solution

See Tenant is throttled because the rate limit is exceeded .

Getting ECONNREFUSED when using Postman Client

If REST calls from Postman Client return an ECONNREFUSED error, the BaaS Enable Session Provider Server setting is probably disabled.

Solution

Run this command from the Command Palette:

BaaS: Open Settings

Ensure that the Enable Session Provider Server setting is enabled.

Invalid ZIP file error due to missing manifest

Build or generate operations can fail when the service workspace contains an invalid ZIP file with a missing manifest.

Symptoms

Build or generate operations fail with errors that indicate a missing manifest file.

Root cause

The service workspace folder structure is invalid. The UniqueServiceName folder contains another folder with the same name that contains the workspace. For example:

git/baasProjects/uniqueservicename/uniqueservicename/workspace.code-workspace

Solution

Remove the top-level folder so that the workspace is directly inside the UniqueServiceName folder.

Verify that the workspace file is located in the correct directory structure.

Preventive measures

Verify the selected folder structure when you create the BaaS service workspace.

Invalid upload target error due to StorageHandler prefix or suffix match

An exception occurs when you upload or copy a storage key from within a StorageHandler and the upload target matches the configured prefix or suffix.

Symptoms

Upload or copy operations fail when they are executed from within a StorageHandler.

Root cause

The supports(FileInfo) function in the StorageHandler returns true or matches the configured prefix or suffix for the upload target. The SDK prevents this configuration to avoid infinite loops.

Solution

Ensure that the supports(FileInfo) function does not return true for the upload target.

Update the supports(FileInfo) function so that it matches only the intended prefix or suffix defined in the manifest.

Upload the file to a different key if required.

Preventive measures

Ensure that the supports(FileInfo) function logic matches only valid upload targets and does not overlap with StorageHandler prefixes or suffixes.