Troubleshooting

Common problems, what causes them, and current limitations you should design around.

Symptom, cause and fix at a glance

What you see	Cause	Fix
`401` when Gradle resolves a `com.bigledger` dependency	Your token is missing or expired, or lacks the `read:packages` scope	Fix the credentials
`Could not find com.bigledger:akaun-api:<version>`	Your account has no read access yet, or the version does not exist (1.0.0, 1.1.0 and 1.2.0 do)	Ask for access, check the version
`cannot find symbol` on a BigLedger import	`javasdk` is not declared, so it is absent from your compile classpath	Declare `javasdk` too
Startup stops with `Please pass in a value for DB_HOST in environment variables.` (or another `DB_` name)	`WebserviceApplication` reads the master connection while it loads, and that variable is missing	Set all five `DB_` variables
Startup fails with an ambiguous mapping error	One of your routes matches a BigLedger route and method exactly	Move it under your `x-` segment
BigLedger’s routes answer and yours return `404`	Your `@SpringBootApplication` class is not a Spring source, or is not at the root of your packages	Register both sources
Your endpoint answers `CLIENT_TENANT_CODE_IS_EMPTY`	The request carries no tenant code	Send it in a `tenantCode` header
Your endpoint answers `CLIENT_TENANT_CODE_DOES_NOT_EXIST` for a tenant you know exists	Your `DB_` variables point at a different environment’s master database from the one your client signs in to	Point both at the same environment
Your endpoint answers a user who should not see the data	The handler has no permission check	Call `isUserPermitted` with `tntInfo.dbConn`, as Adding a REST endpoint shows
A Jasper print or PDF template fails at runtime, though everything compiled	It depends on bundled jars that published dependency metadata does not carry	A known gap: raise it before you build on it
Your log shows clock and webhook processing you never wrote	The scheduled-work thread that loading the platform starts (What your process takes on)	Give each development copy its own database
After an upgrade, queries fail on columns that do not exist	The database was not migrated to the new release	Have the database’s administrator run the migration before you deploy

Every code value above has its meaning and next step on Error Codes.

Access and download problems

`401 Unauthorized` when resolving dependencies

Your token is missing, expired, or lacks the right scope.

Confirm gpr.user and gpr.key are in your user-level ~/.gradle/gradle.properties, not the project’s copy
Confirm the token has the read:packages scope
Confirm the token has not expired

On a build server, check that GITHUB_ACTOR and GITHUB_TOKEN are reaching the build — a secret that is defined but not passed into the job produces exactly this error.

`Could not find com.bigledger:akaun-api:1.0.0`

Either your account has no read access to the packages, or the version does not exist.

Ask your BigLedger contact to confirm access has been granted to your account or team
Check the version number for typos, and confirm the release exists
Confirm the repository URL is exactly https://maven.pkg.github.com/bigledger/blg-akaun-platform-java

The first build seems to hang

It is downloading. The BigLedger artifacts are large — tens of megabytes before their dependencies, and the dependency tree behind them is larger still. Later builds use the local cache.

Compilation problems

`cannot find symbol` on a BigLedger import

The most common cause is a missing javasdk dependency. akaun-api exposes javasdk at runtime scope only, so it is not on your compile classpath unless you declare it yourself:

implementation("com.bigledger:akaun-api:1.0.0")
implementation("com.bigledger:javasdk:1.0.0")   // required

If both are declared and the symbol is still missing, the class may be internal to the platform and not part of the published surface.

Version conflicts with your own dependencies

The platform brings a large dependency tree, including Spring, Jackson, Guava and the AWS SDK. If one of your own libraries needs a different version of something, inspect the resolution first:

./gradlew dependencyInsight --dependency jackson-databind --configuration compileClasspath

Prefer aligning with the version the platform brings. Forcing a different version can produce failures at runtime that compile perfectly.

Startup problems

The application fails to start with an ambiguous mapping error

Two controllers are mapped to the same path and HTTP method — almost always one of yours colliding with a BigLedger route. Move your endpoint into your own x- namespace, which no BigLedger route uses today, for example …/x-yourcompany/…. See URL naming.

The application fails to start with a database error

BigLedger connects to the master database during startup. Confirm DB_HOST, DB_PORT, DB_USER, DB_PASS and DB_NAME are all set and reachable from where the application runs.

Your beans are not picked up

Your @SpringBootApplication class must be at the root of your package tree so component scanning reaches your controllers and services, and it must be registered alongside BigLedger’s application class:

.sources(WebserviceApplication.class, YourApplication.class)

If only WebserviceApplication is listed, BigLedger starts but none of your code loads.

After an upgrade, queries fail on columns or tables that do not exist

The application is on the new version and the database is not. Starting the application never migrates a database. Somebody holding a platform system administrator login has to call the migration route on a process already running the new version. Versioning & Upgrades has the call and the check that proves it worked.

Current limitations

These are known characteristics of the current release. Design around them rather than working against them.

Some runtime features are unavailable

A small number of platform capabilities depend on libraries that published dependency metadata has no way to express. In applications built on the platform libraries, these fail at runtime, although everything compiles normally:

Jasper-based printing and PDF templates — depends on bundled font libraries
The Lazada marketplace integration — depends on a bundled vendor SDK

This is a known gap. If your application needs either capability, raise it with your BigLedger contact before you build on it.

No extension points for existing behaviour

You can add endpoints, services and data. You cannot change how existing BigLedger endpoints and services behave — there are no published hooks, filters or replaceable strategies in this release. See Changing existing behaviour for the supported alternatives.

Do not modify platform behaviour by other means

Patching platform classes, shadowing them on the classpath, or overriding them by package name may appear to work. It is unsupported, and it is likely to break without warning at your next upgrade. If you find yourself reaching for one of these, raise the requirement with BigLedger instead.

Getting help

When reporting a problem, include:

The platform version you are on, for example 1.0.0
The full error message and stack trace
Your Java and Gradle versions (java -version, ./gradlew --version)
The relevant part of your build file
Whether the problem occurs at dependency resolution, compilation, startup, or runtime

Please do not include tokens, passwords, database credentials or real customer data in a report.