Skip to content

KB-210 – ADempiere Core Debugging Guide

Knowledge Base ID: KB-210
Project: BLACK ERP
Version: 1.0
Status: Certified
Last Updated: 2026-06-26
Applies To: ADempiere 3.9.4

Purpose

This document defines the official debugging methodology for BLACK ERP Core Java development.

It provides a structured engineering process to diagnose build, deployment, runtime and accounting issues within ADempiere.

Rather than relying on trial and error, every issue shall be investigated following a repeatable diagnostic workflow.

This guide was validated during the implementation of the Mexican VAT Cash Basis (IVA al Pago) accounting engine.

Engineering Philosophy

Debugging is an engineering activity.

Every issue shall be investigated by collecting evidence until the root cause is identified.

Never modify code based on assumptions.

Always validate each layer independently.

Debugging Categories

Most Core Java issues belong to one of the following categories.

Category Examples
Source Code Java logic, syntax, inheritance
Compilation compile errors, missing imports
Build Ant targets, generated artifacts
Packaging setupALib, packages.jar
Deployment wrong runtime JAR, outdated libraries
Runtime ClassNotFoundException, NoClassDefFoundError
Security SHA-256 digest, signed JAR errors
Database SQL, metadata, dictionary
Accounting Posting engine, Fact creation
Functional Business process validation

Official Debugging Workflow

Every investigation shall follow the same sequence.

Problem Report
        │
        ▼
Reproduce Issue
        │
        ▼
Collect Evidence
        │
        ▼
Classify Problem
        │
        ▼
Validate Source
        │
        ▼
Validate Build
        │
        ▼
Validate Runtime
        │
        ▼
Validate Deployment
        │
        ▼
Validate Functional Process
        │
        ▼
Root Cause
        │
        ▼
Corrective Action
        │
        ▼
Regression Test
        │
        ▼
Knowledge Base Update

Source Validation

Verify that the expected source code exists.

Typical checks:

  • Java class
  • Package
  • Imports
  • Inheritance
  • Interfaces
  • Modified methods

Example:

grep -R "MXVATCashBasisEngine" .

Compilation Validation

Compile the affected module.

Example:

cd source/base

ant compile

Expected:

BUILD SUCCESSFUL

Compilation success only proves the source code is valid.

It does not prove that production has been updated.

Build Validation

Verify that the generated artifact contains the expected classes.

Typical commands:

jar tf Adempiere.jar

jar tvf Adempiere.jar

sha256sum Adempiere.jar

Questions:

  • Does the class exist?
  • Was it rebuilt?
  • Is the timestamp correct?

Runtime Validation

Confirm that production is actually using the expected runtime.

Typical checks:

jar tf

jar tvf

sha256sum

Compare:

source/lib

install/build/lib

Adempiere/lib

tomcat/lib

Never assume that identical filenames contain identical binaries.

Deployment Validation

Verify that deployment completed correctly.

Check:

  • Runtime JAR
  • Packages
  • Tomcat libraries
  • Restart
  • Cache cleanup

Required validation:

systemctl restart adempiere.service

curl http://127.0.0.1:8080/webui/

tail catalina.out

Runtime Error Investigation

Common runtime errors include:

ClassNotFoundException

Usually indicates:

  • Missing package
  • Incorrect runtime JAR
  • Incomplete deployment

NoClassDefFoundError

Usually indicates:

  • Missing dependency
  • Incompatible runtime

SecurityException

Usually indicates:

  • Modified signed JAR
  • Invalid SHA-256 digest
  • Broken digital signature

HTTP 404

Usually indicates:

  • Deployment failure
  • Missing web application

HTTP 500

Usually indicates:

  • Runtime exception
  • Startup failure
  • Initialization error

Accounting Validation

Accounting changes require additional verification.

Minimum checklist:

  • Document completes
  • Posting succeeds
  • Facts generated
  • Expected accounts used
  • Debit/Credit balanced
  • Allocation posts successfully

Never validate accounting changes using compilation alone.

Functional posting is mandatory.

Production Validation

After every deployment verify:

  • Login
  • Open Windows
  • Complete Documents
  • Payment
  • Allocation
  • Posting
  • Accounting Facts

No deployment is complete until functional validation succeeds.

Useful Diagnostic Commands

Search a class

jar tf Adempiere.jar | grep ClassName

Verify timestamp

jar tvf Adempiere.jar

Compare JARs

sha256sum

Compare file contents

comm

diff

Search logs

grep

tail

less

Verify services

systemctl

curl

Lessons Learned

The MX VAT Cash Basis implementation provided several important engineering lessons.

  • Successful compilation does not guarantee successful deployment.
  • clientDistribute generates an intermediate artifact.
  • setupALib generates the certified runtime.
  • Runtime packaging must be preserved.
  • Signed JARs must never be modified directly in production.
  • Functional validation is mandatory.
  • Every deployment must end with a regression test.

Debugging Principles

  1. Never guess.
  2. Always collect evidence.
  3. Validate one layer at a time.
  4. Separate compilation from deployment.
  5. Separate deployment from runtime.
  6. Functional validation is mandatory.
  7. Document every certified lesson.

Related Knowledge Base

  • KB-208 – Core Development Lifecycle
  • KB-209 – ADempiere Runtime Architecture
  • KB-211 – Packaging & Digital Signatures

Revision History

Version Date Description
1.0 2026-06-26 Initial certified debugging methodology.