TIL: Fixing “Cannot Find onconfig File” in GBase Database

Today I helped troubleshoot a GBase Database(GBase 8s) instance that failed to start. The error looked like a missing configuration file, but the real problem was incorrect environment variables. If oninit -ivy appears to do nothing and the log reports Cannot find onconfig file, checking your environment variables should be one of the first steps.

The Symptoms

After running:

oninit -ivy

Enter fullscreen mode Exit fullscreen mode

there was no visible output, and the GBase Database instance did not start.

Checking the online log showed:

GBASERMT Cannot find onconfig file

Enter fullscreen mode Exit fullscreen mode

At first, this looks like an onconfig file problem. However, the file was actually present. The issue was that GBase Database could not locate it through the configured environment.

The Root Cause

GBase Database(GBase 8s) uses several environment variables to locate its installation directory, instance configuration, and connectivity files.

A typical environment looks like this:

export GBASEDBTDIR=/opt/GBASE/gbase
export GBASEDBTSERVER=gbase01
export ONCONFIG=onconfig.gbase01
export GBASEDBTSQLHOSTS=$GBASEDBTDIR/etc/sqlhosts.gbase01
export DB_LOCALE=zh_CN.utf8
export CLIENT_LOCALE=zh_CN.utf8
export GL_USEGLU=1

Enter fullscreen mode Exit fullscreen mode

After modifying the environment, reload it:

source ~/.bash_profile

Enter fullscreen mode Exit fullscreen mode

Then verify the critical variables:

echo $GBASEDBTDIR
echo $GBASEDBTSERVER
echo $ONCONFIG
echo $GBASEDBTSQLHOSTS

Enter fullscreen mode Exit fullscreen mode

Common GBase Database Configuration Mistakes

1. GBASEDBTDIR Points to the Wrong Directory

A common mistake is accidentally adding an extra directory level:

export GBASEDBTDIR=/opt/GBASE/gbase/gbase

Enter fullscreen mode Exit fullscreen mode

when the actual installation directory is:

export GBASEDBTDIR=/opt/GBASE/gbase

Enter fullscreen mode Exit fullscreen mode

Check whether the GBase Database executable exists:

ls $GBASEDBTDIR/bin/oninit

Enter fullscreen mode Exit fullscreen mode

If oninit cannot be found, fix GBASEDBTDIR first.

2. ONCONFIG Does Not Match the Configuration File

Check the available configuration files:

ls $GBASEDBTDIR/etc/onconfig.*

Enter fullscreen mode Exit fullscreen mode

Then make sure ONCONFIG matches the actual filename:

export ONCONFIG=onconfig.gbase01

Enter fullscreen mode Exit fullscreen mode

The filename and the ONCONFIG value must correspond.

3. GBASEDBTSQLHOSTS Points to a Missing File

Check the configured sqlhosts path:

echo $GBASEDBTSQLHOSTS
cat $GBASEDBTSQLHOSTS

Enter fullscreen mode Exit fullscreen mode

If the file does not exist, verify the intended location and create or restore the correct sqlhosts configuration.

For example:

cat > $GBASEDBTSQLHOSTS <<EOF
gbase01 onsoctcp 192.168.1.100 9088
EOF

Enter fullscreen mode Exit fullscreen mode

Use the actual hostname, protocol, IP address, and port for your environment rather than copying these values directly.

Quick Diagnostic Script

When troubleshooting a GBase Database startup problem, this simple script can quickly identify missing variables and files:

#!/bin/bash

echo "=== Environment Variable Check ==="
echo "GBASEDBTDIR: ${GBASEDBTDIR:-[NOT SET]}"
echo "GBASEDBTSERVER: ${GBASEDBTSERVER:-[NOT SET]}"
echo "ONCONFIG: ${ONCONFIG:-[NOT SET]}"
echo "GBASEDBTSQLHOSTS: ${GBASEDBTSQLHOSTS:-[NOT SET]}"

echo ""
echo "=== Critical File Check ==="
[ -f "$GBASEDBTDIR/bin/oninit" ] \
  && echo "[OK] oninit exists" \
  || echo "[ERROR] oninit missing"

[ -f "$GBASEDBTDIR/etc/$ONCONFIG" ] \
  && echo "[OK] onconfig exists" \
  || echo "[ERROR] onconfig missing"

[ -f "$GBASEDBTSQLHOSTS" ] \
  && echo "[OK] sqlhosts exists" \
  || echo "[ERROR] sqlhosts missing"

Enter fullscreen mode Exit fullscreen mode

The Key Lesson

When GBase Database fails to start with an onconfig-related error, do not immediately assume that the configuration file is corrupted or missing.

Check these first:

1. Is GBASEDBTDIR correct?
2. Does $GBASEDBTDIR/bin/oninit exist?
3. Does ONCONFIG match the actual configuration filename?
4. Does $GBASEDBTSQLHOSTS point to the correct file?
5. Have you reloaded the environment after making changes?

If you have worked with Informix-style database administration before, these environment variables will look familiar. For repeatable deployments, putting them into a dedicated environment script can also reduce startup and configuration errors.

Bottom line: many GBase Database startup failures are not caused by the database engine itself. Sometimes, the problem is simply that the instance does not know where to find its own configuration.