Part 1: Setup and Configuration
A practical guide for Oracle developers on Windows including real errors encountered, exact fixes applied, and lessons learned along the way.
By Malik Sikandar Hayat | Oracle ACE Pro | ERPstuff.com | admin@erpstuff.com
________________________________________
What is APEXlang
APEXlang is a new declarative language introduced in Oracle APEX 26.1 that allows you to describe your entire APEX application in plain human readable text files. Each file has the extension .apx and represents a page, a shared component, or application level settings. Instead of clicking through the APEX Builder interface to create pages and regions, you write or edit these .apx files in VS Code and use an AI assistant like Claude to help you build your application faster. Once you are done editing you push the changes back into APEX using either a single click in VS Code or a command in SQLcl.
This is not just a file format change. APEXlang is designed to work with AI coding agents. The .apx files are structured and readable enough that Claude can understand them, modify them correctly, and generate new ones following the exact property names and valid values that the APEX compiler expects. This makes AI assisted APEX development practical for the first time.
________________________________________Important: APEXlang is only available in Oracle APEX 26.1 and higher. It does not work on any earlier version.
What You Need to Download and Install
You need eight pieces of software before you can start. Install them in the order listed here because some depend on others being present first.
1. Oracle Database 26ai Free
Download: https://www.oracle.com/database/free/get-started/
This installs the DB engine, listener on port 1522, and includes bundled copies of SQLcl and ORDS. However the bundled copies have issues on Windows covered in detail below. Download the standalone versions separately.
2. Java 17 (Oracle JDK)
Download: https://www.oracle.com/java/technologie ... ds/#java17
SQLcl requires Java 17 as a minimum. Oracle 26ai Free may install its own Java but it can conflict with SQLcl. Always install the standalone Oracle JDK 17.
3. Oracle APEX 26.1
Download: https://www.oracle.com/tools/downloads/apex-downloads/
Install into your Oracle 26ai Free following the standard APEX installation steps.
4. Oracle ORDS 26.1.1
Download: https://www.oracle.com/database/sqldeve ... /download/
ORDS is the web server that makes APEX accessible in your browser. Install after APEX.
5. SQLcl 26.1.2 (Standalone)
Download: https://www.oracle.com/database/sqldeve ... /download/
Oracle 26ai Free includes a bundled SQLcl but it is broken on Windows. Install this standalone version separately.
6. VS Code
Download: https://code.visualstudio.com/download
The code editor where you will edit .apx files and interact with Claude.
7. Git
Download: https://git-scm.com/download/win
Required to clone the Oracle skills repository.
8. Node.js 18+
Download: https://nodejs.org/
Required to run the skills installer command.
________________________________________
Setting Up SQLcl Correctly
After installing Oracle 26ai Free you will find two copies of SQLcl on your machine. One is bundled inside the Oracle home folder and the other is the standalone version you download separately. The bundled version is broken on Windows and cannot be used for APEXlang work.
This error happens because the bundled SQLcl inside Oracle 26ai Free has missing or incompatible class files. The standalone SQLcl downloaded separately works correctly.Error: Broken Bundled SQLclFix: Always use the standalone SQLcl at C:\app\PC\product\26ai\sqlcl\bin\sql.exe and never the one inside dbhomeFree\bin\Code: Select all
Error: Unable to initialize main class oracle.dbtools.raptor.scriptrunner.cmdline.SqlCli Caused by: java.lang.NoClassDefFoundError: oracle/dbtools/core/util/MessageLogger$ErrorLogger
To make Windows always use the correct standalone SQLcl you need to put the standalone SQLcl bin folder at the front of your system PATH. Open PowerShell as Administrator, add the path C:\app\PC\product\26ai\sqlcl\bin to the beginning of your Machine level PATH environment variable, then close and reopen PowerShell. After that run sql with the version flag to confirm you see SQLcl Release 26.1.2.0 Production Build in the output.
________________________________________Tip: If the broken version is still winning in the PATH after updating it, always call the standalone SQLcl using its full path directly instead of just the sql command.
Understanding Thick and Thin Oracle JDBC Drivers
Before explaining the next error it is important to understand the difference between the two Oracle JDBC driver modes because this is the root cause of the most frustrating issue in the entire setup.
The Thick Client
The thick client, also called the OCI driver, requires Oracle Client native libraries to be installed on your machine. It loads native DLL files from your Oracle Home directory at runtime and communicates with the Oracle engine through those native libraries. It supports more advanced Oracle features and historically offered better performance but it is tightly coupled to the specific version of the Oracle Client installed on your machine. If the DLL version and the JDBC driver version do not match exactly the connection fails.
The Thin Client
The thin client is a pure Java driver. It has no dependency on any Oracle Client libraries or native DLL files. It connects directly to the Oracle engine over TCP using the Oracle Net protocol implemented entirely in Java. It is simpler, more portable, and works anywhere Java runs without needing any Oracle software installed beyond the JDBC jar files themselves.
On a typical developer machine where only one Oracle version is installed both drivers usually work fine. The problem arises on Oracle 26ai Free on Windows where the native OCI library version and the JDBC driver version bundled inside SQLcl 26.1.2 do not match. The thick client fails to load because of this version mismatch.
________________________________________
The OCI Driver Error and the ORA-17012 Bug
When you try to connect to your Oracle instance using SQLcl without specifying the driver mode you will see a connection failure about an incompatible version of libocijdbc.
Even if the connection somehow proceeds, running apex validate or apex import will fail with ORA-17012. This error is caused by a bug in the OCI thick client where it mismatches the parameter type when SQLcl internally calls the APEX PL/SQL APIs. The thick client passes a parameter type that conflicts with what the APEX procedure expects and Oracle throws ORA-17012 as a result. This is not an issue with your code or your application. It is a driver level bug specific to the version mismatch between SQLcl 26.1.2 and Oracle 26ai Free on Windows.Error: OCI Driver Version MismatchFix: Add -thin to every SQLcl connection command to use the pure Java driver instead of the OCI thick clientCode: Select all
Connection failed Error Message = Incompatible version of libocijdbc[Jdbc:23702501, Jdbc-OCI:2326000
This ORA-17012 error confused us for a long time because it appears even when the connection itself succeeds. We eventually found the fix through an Oracle community post from another developer who hit the same issue. The solution is to always add -thin to every SQLcl connection command.Error: ORA-17012 During apex validate or apex importFix: This is not a code error. It is a known OCI thick client bug. Add -thin to your SQLcl connection and it disappears completelyCode: Select all
ORA-17012: Parameter type conflict: sqlType=2 https://docs.oracle.com/error-help/db/ora-17012/
Example of correct connection:Warning: The -thin flag is mandatory on Windows with Oracle 26ai Free for every SQLcl connection. There are no exceptions. apex validate and apex import will both fail without it.
Code: Select all
C:\app\PC\product\26ai\sqlcl\bin\sql.exe -thin ERPSTUFF/your_password@localhost:1522/freepdb1Setting Up ORDS to Start Easily
ORDS does not start automatically when Windows boots. Every time you restart your PC you need to start ORDS manually before you can access APEX in your browser. Rather than configuring it as a Windows service which involves additional complexity the simplest reliable approach is to create two batch files.
Create a file named ords-start.bat and save it somewhere easy to find such as your desktop or the root of your C drive:
Code: Select all
@echo off
echo Starting ORDS...
C:\app\PC\product\26ai\ords26\bin\ords.exe serve --port 8080Code: Select all
@echo off
echo Stopping ORDS...
for /f "tokens=5" %%a in ('netstat -aon ^| findstr ":8080"') do (
taskkill /F /PID %%a
)
echo ORDS Stopped.
pause________________________________________
Installing VS Code Extensions
Open VS Code and press Ctrl Shift X to open the Extensions panel. You need two extensions installed before you can work with APEXlang.
1. Oracle SQL Developer Extension for VS Code published by Oracle Corporation. Search for Oracle SQL Developer and install version 26.1.2. This extension provides the connection panel, APEXlang syntax validation directly inside the editor as you type, and the Import Sync button that pushes your .apx changes directly into APEX with a single click.
2. Claude Code for VS Code published by Anthropic. Search for Claude Code and install it. This is the AI assistant that reads your project skills and generates APEXlang files based on your natural language instructions.
After installing both extensions add your connection. Click the Oracle icon in the VS Code left sidebar to open the SQL Developer panel. Click the plus button to add a new connection and fill in your host as localhost, port as 1522, service name as freepdb1, and your APEX parsing schema username and password. Once connected you will see your APEX applications listed under the APEX section.
________________________________________
Installing Oracle Skills for Claude
This step is critical and must not be skipped. Oracle has published an official skills repository on GitHub that teaches Claude the exact correct APEXlang syntax for every APEX component type. Without these skills Claude guesses property names and generates .apx files with wrong syntax that the APEX compiler rejects.
Step 1 - Clone the repository for local reference:We learned this the hard way. Without the skills installed Claude generated an interactive report page using wrong property names. The compiler rejected every property and the import failed. After installing the skills and regenerating the file the correct syntax was produced and the import succeeded.
Code: Select all
cd D:\Downloads\OracleAPEX26_1
git clone https://github.com/oracle/skills.git apex-skillsCode: Select all
npx skills add oracle/skills/apex
npx skills add oracle/skills/dbStep 3 - Verify installation in PowerShell:
Code: Select all
Get-ChildItem "$env:USERPROFILE\.claude\skills" -Recurse | Select-Object FullName________________________________________Warning: Installing skills does not guarantee Claude will always generate perfect APEXlang. The skills are reference documents Claude consults. For complex components like form pages Claude can still make mistakes. Always validate after every generation.
Creating the CLAUDE.md File
Claude Code reads a file named CLAUDE.md from your project root at the start of every session. This file acts as persistent memory for Claude giving it your connection details, application ID, workspace name, available commands, and development rules. Without this file you have to repeat your environment details on every single session.
Create a file named CLAUDE.md in your project root folder with this content:
Code: Select all
# APEX Project
## Environment
Oracle APEX 26.1.0
Host: localhost
Port: 1522
Service: freepdb1
ORDS URL: http://localhost:8080/ords
Workspace: ERPSTUFF
Parsing Schema: ERPSTUFF
App ID: 105
## SQLcl Connection
C:\app\PC\product\26ai\sqlcl\bin\sql.exe -thin ERPSTUFF/password@localhost:1522/freepdb1
## Commands
Validate: apex validate -input pages
Import: apex import -input pages
## Rules
- Always use -thin flag when connecting via SQLcl
- All .apx files must use LF line endings not CRLF
- Read skills reference files before generating any .apx file
- Never guess APEXlang syntax
- All PL/SQL must have EXCEPTION blocks
- Use bind variables always
- After any export or Claude generation run the CRLF fix script before validatingThe CRLF Line Endings Problem
This was the most persistent issue in the entire setup and it has two separate causes that both need to be understood.
Why CRLF Happens
The APEXlang compiler requires Unix style LF line endings in all .apx files. On Windows every line in a text file ends with two characters, a carriage return followed by a line feed, written as CRLF. The APEXlang compiler expects LF only and when it encounters CRLF it silently ignores the entire file with a FILE_IGNORED warning.
First Source: APEX Builder Export on WindowsError: FILE_IGNORED Warning During ValidationFix: This is not actually successful. Every file was ignored due to CRLF line endings. Run the CRLF fix PowerShell script on all .apx files then validate againCode: Select all
File: p00001-home.apx Type: FILE_IGNORED Warning: APEXlang source file ignored. Validation successful.
When you export an application from APEX Builder running on Windows it saves all .apx files with CRLF line endings. This is a bug in APEX 26.1 on Windows. Oracle is expected to fix it in a future release.
Second Source: Claude Code File Generation on Windows
When Claude Code generates a new .apx file and saves it to your project folder on Windows it also uses CRLF line endings because VS Code on Windows defaults to CRLF for new files unless explicitly configured otherwise.
The Fix
Run this PowerShell script after every APEX Builder export and after every Claude Code file generation:
Code: Select all
Get-ChildItem "D:\YourProject\pages\*.apx" | ForEach-Object {
$content = [System.IO.File]::ReadAllText($_.FullName)
$content = $content -replace "`r`n", "`n"
[System.IO.File]::WriteAllText($_.FullName, $content, [System.Text.UTF8Encoding]::new($false))
Write-Host "Fixed: $($_.Name)"
}________________________________________
Known Limitations of AI Generated APEXlang
Even after installing the Oracle skills Claude can still generate incorrect APEXlang in certain situations.
BOM Character at Start of File
Some editors and AI tools on Windows save files with an invisible UTF-8 BOM character at the very beginning of the file. The APEXlang compiler does not accept this and immediately reports a token recognition error at line zero. The CRLF fix script handles this automatically.
Wrong Region Reference Syntax in Form Pages
When generating a form page with multiple page items Claude sometimes uses a region reference identifier that does not exactly match the declared region name. APEXlang uses the at sign prefix to reference regions from page items and the identifier must match exactly including case and spelling. If Claude gets this wrong the compiler reports Reference not found errors for every page item in the region.
Invalid Properties in Page Item Source Blocks
For form page items Claude sometimes uses incorrect property names inside the source block. Properties like column, dataType, queryOnly, and primaryKey are not always valid in the same context. The correct property names depend on the region type and Claude may not always consult the exact right reference file before generating these blocks.
The practical approach for all of these issues is the same. Always validate after every generation using apex validate with the -thin flag. Share exact error messages with Claude and ask it to fix only the specific failing properties. The validate command is your safety net and must be run before every import.
________________________________________
Verification Checklist
Before moving to Part 2 confirm all of the following items are working correctly on your machine.
1. ORDS starts successfully and APEX opens at http://localhost:8080/ords/apex
2. SQLcl connects without errors using the -thin flag
3. VS Code shows your connection in the SQL Developer panel with APEX applications visible
4. Oracle skills are installed and visible inside C:\Users\YourName\.claude\skills\
5. CLAUDE.md exists in your project root with correct environment details filled in
6. You have tested the CRLF fix PowerShell script and confirmed it runs without error
Once all items are confirmed you are ready for Part 2 which covers exporting your first application from APEX Builder as APEXlang, working with Claude Code to generate new pages, validating your changes, and importing back into APEX.
________________________________________
ERPstuff.com | Oracle ACE Pro Community | admin@erpstuff.com | Since 2006