SAP HANA XSA Basics: Architecture, Deployment, and Troubleshooting

01Understand the XSA architecture

SAP HANA XS Advanced, commonly called XSA, is an application platform for running services and applications alongside SAP HANA. It supports modern application runtimes, multiple programming languages, independent deployment units, and controlled access to database resources.

An XSA installation is organized around several platform components:

• The Cloud Foundry-based application runtime schedules and runs application processes.
• The XS controller manages organizations, spaces, users, applications, routes, and services.
• The UAA provides authentication and authorization services.
• The application router receives HTTP requests and forwards them to application routes.
• The database and HDI services provide persistence and database artifacts.
• The xs CLI provides command-line access to platform operations.

The platform separates application deployment from database design-time content. This separation makes it possible to deploy a database module, service module, and user interface module as coordinated parts of one application while keeping their responsibilities distinct.

02Compare XSA and XSC

XS Advanced and XS Classic solve related application-platform problems but use different development and runtime models. XS Classic uses the XS engine embedded in the SAP HANA database and commonly hosts XS JavaScript applications and repository-based artifacts. XSA uses separate application processes and supports Cloud Foundry-style deployment concepts.

For new application work, identify the runtime and deployment model before selecting templates or tools. The platform model determines how authentication, database access, routes, and deployment pipelines are configured.

For the broader development landscape, see SAP HANA development overview. Database modeling choices are covered in SAP HANA calculation views.

03Work with organizations and spaces

An XSA organization groups platform resources under an administrative boundary. A space is a subdivision within an organization where applications, services, routes, and user permissions are managed. Application commands operate against the currently targeted organization and space.

A typical CLI session begins by logging in and targeting the correct space:

xs login -a https://<xsa-api-host> -u <user>
xs target -o <organization> -s <space>

Use a separate space for each lifecycle or application boundary that requires independent access control. Before deploying, verify the target with the CLI and confirm that the selected space contains the expected applications and services.

A deployment performed in the wrong space can still succeed, so target verification is an operational control rather than an optional diagnostic step.

04Deploy an XSA application

XSA applications are commonly delivered as a multi-target application, or MTA. An MTA groups related modules and describes their dependencies, provided services, required services, routes, and deployment parameters in an mta.yaml file.

A practical deployment sequence is:

1. Build the application modules and database artifacts.
2. Validate the mta.yaml descriptor.
3. Package the application as an MTA archive.
4. Target the intended organization and space.
5. Deploy the archive with the MTA deployment command.
6. Review application status, routes, service instances, and logs.
7. Test authentication and application-to-database access.

A representative command is:

xs deploy <application>.mtar

The deployment descriptor should define clear module names, service requirements, and environment-specific parameters. Keep secrets out of source control and supply them through protected deployment configuration or platform-managed services.

For database modules, use HDI-compatible artifacts and grant the required access through declared dependencies. SAP HANA HDI containers explains the container model and its role in application development.

05Configure routes and service bindings

A route maps an externally reachable host and path to an application. The route must resolve to the intended application process, and the application must listen on the port supplied through its runtime environment.

Service bindings expose connection information to an application. In an MTA, a module declares a required service and the deployment descriptor connects that requirement to a service instance. The application then reads the injected environment configuration rather than embedding database credentials in source code.

Check these items when a deployed application cannot reach its database:

• The service instance exists in the target space.
• The application module declares the service as a required dependency.
• The binding was created after deployment or update.
• The application restarted after binding changes.
• The application reads the platform-provided connection information.
• The HDI container user has the required object privileges.

A successful service binding does not guarantee that the application uses the binding correctly. Inspect the application environment and startup logs when the process starts but database requests fail.

06Manage authentication and authorization

XSA applications commonly use UAA-based authentication and OAuth flows. The application router can handle login and forward authenticated requests, while application services validate tokens and enforce authorization decisions.

Separate these responsibilities:

• Authentication confirms the identity associated with a request.
• Token validation confirms that the token is trusted and usable.
• Authorization determines whether the identity may perform a requested operation.
• Database privileges control access to database objects and procedures.

Configure redirect URIs and route hosts consistently across the application router, identity configuration, and client registration. A mismatch can produce login loops, invalid redirect errors, or requests that reach the application without the expected user context.

Use least-privilege roles for application users and technical users. Database access should be granted through the application’s intended HDI role model rather than broad administrative privileges.

07Troubleshoot deployment failures

Start with the layer that failed. A build error, upload error, staging error, process crash, route failure, and database authorization error require different evidence.

Useful first checks include:

xs apps
xs services
xs env <app-name>
xs logs <app-name> --recent

Interpret the results in this order:

1. Application state: Confirm that the application instance is started and has the expected number of processes.
2. Route resolution: Confirm that the route is mapped to the intended application.
3. Environment: Check that required environment values and service credentials are present.
4. Recent logs: Look for startup exceptions, port errors, missing modules, and authentication failures.
5. Service state: Confirm that dependent services are available and bound.
6. Database authorization: Verify that the deployed database artifacts and roles support the requested operation.

A process that repeatedly stops often indicates a startup or dependency problem. A running process that returns HTTP errors usually requires route, authentication, application, or database investigation.

For application-level testing and diagnostics, see SAP HANA application testing and debugging. For performance-related application issues, see SAP HANA developer performance tuning.

08Operate XSA safely

Treat XSA operations as a combination of platform administration, application lifecycle management, and database security. Record the target organization and space for each deployment, retain deployment logs, and use controlled permissions for platform and database operations.

Establish repeatable checks for:

• Application process health and restart counts
• Route availability and certificate validity
• Service instance health and binding status
• Authentication configuration and token behavior
• HDI container deployment status
• Application and database log retention
• Backup and recovery procedures for the underlying SAP HANA system

Use separate deployment identities for automation and human administration. Rotate credentials through an approved process, test changes in a controlled space, and preserve the previous deployment artifact so that a rollback can be performed with a known version.

XSA troubleshooting is most effective when each deployment has a clear application version, descriptor version, target space, service-binding state, and corresponding log set.