Meta Description: Troubleshoot GBase Database(GBase 8s) instance startup failures with five practical checks covering rootdbs permissions, ROOTPATH, sqlhosts, environment variables, and character set configuration.
When a GBase Database instance fails to initialize, the error message is often only one or two lines long. The actual cause may be hidden in a directory, file permission, network configuration, or environment variable.
For GBase Database(GBase 8s), troubleshooting becomes much easier when you check the environment layer by layer instead of repeatedly running initialization commands.
This guide covers five common causes of instance initialization failures, explains their symptoms, and provides commands to verify each one.
1. Incorrect rootdbs Ownership or Permissions
One common cause of GBase Database initialization failure is incorrect ownership or permissions on the root database space file.
Typical symptom: oninit -ivy hangs or exits unexpectedly during initialization.
Check the file:
ls -l /opt/GBASE/gbase/dbs/rootdbs The expected configuration is:
- Owner:
gbasedbt - Group:
gbasedbt - Permission:
660
If the file was created by root and ownership was never changed, the database process may not have sufficient permissions to write the required reserved page.
Correct it with:
chown gbasedbt:gbasedbt /opt/GBASE/gbase/dbs/rootdbs chmod 660 /opt/GBASE/gbase/dbs/rootdbs Also verify the parent directory:
ls -ld /opt/GBASE/gbase/dbs Troubleshooting principle: Check file ownership and permissions before investigating more complicated initialization errors.
2. ROOTPATH Points to a Nonexistent File
The ROOTPATH parameter in onconfig specifies the location of the root database space.
If the configured file does not exist, initialization cannot proceed correctly.
Check the configuration:
grep '^ROOTPATH' $GBASEDBTDIR/etc/onconfig.gbaseserver Then verify that the referenced file exists:
ls -l /opt/GBASE/gbase/dbs/rootdbs Common causes include:
- A typo in the configured path
- A missing directory
- An incorrect mount point
- A storage volume that was not mounted before startup
Do not assume that a valid configuration line means the underlying file is available.
Troubleshooting principle: Verify the actual file and its storage location, not just the ROOTPATH value.
3. sqlhosts Uses localhost or an Incorrect Port
Sometimes the GBase Database instance starts successfully, but remote applications cannot connect.
The problem may be in the sqlhosts configuration.
Check the file:
cat $GBASEDBTSQLHOSTS A typical entry looks like:
gbaseserver onsoctcp 192.168.127.101 9088 The fields represent:
| Field | Description |
|---|---|
gbaseserver | Instance name |
onsoctcp | Connection protocol |
192.168.127.101 | Server IP address |
9088 | Connection port |
Two mistakes are particularly common.
Using localhost
When remote clients need to connect, using localhost can cause the connection to resolve to the client's own machine rather than the database server.
Port mismatch
The port configured for the database connection must be consistent with the client connection settings and firewall rules.
Troubleshooting principle: Verify the external server address and connection port before investigating application-level authentication.
4. Environment Variables Point to Another Instance
On servers running multiple GBase Database instances, incorrect environment variables can make administrative commands operate against the wrong instance.
A typical symptom is:
shared memory not initialized Yet database processes may still exist on the host.
Check the three key environment variables:
echo $GBASEDBTSERVER echo $ONCONFIG echo $GBASEDBTSQLHOSTS For the target instance, they should consistently reference:
| Variable | Expected value |
|---|---|
GBASEDBTSERVER | gbaseserver |
ONCONFIG | onconfig.gbaseserver |
GBASEDBTSQLHOSTS | The corresponding sqlhosts file |
If only one variable points to another instance, the current shell environment may not match the instance you intend to manage.
This is particularly important on multi-instance hosts, where similar configuration files can make the mistake difficult to notice.
Troubleshooting principle: Confirm all three environment variables together. Checking only one is not enough.
5. Character Set Does Not Match the Site Requirements
Not every initialization problem causes the instance to fail to start.
A character set mismatch may only become visible after importing data or connecting applications.
For example, a script-based initialization may use zh_CN.utf8 as its default character set, while the target environment requires a different setting.
The result can be garbled text or incorrect character representation.
Before initialization, confirm the character set required by:
- Existing business data
- Application clients
- Data migration sources
- Operating environment
- Regional language requirements
Character set selection should be treated as an initialization decision rather than a parameter to postpone until production launch.
Before going live, perform a real data import and verify that the stored and displayed text is correct.
Troubleshooting principle: Validate character set compatibility with actual application data before production deployment.
6. A More Efficient GBase Database Troubleshooting Order
The five problems above belong to different layers. Checking them in a consistent order helps reduce unnecessary investigation.
A practical sequence is:
| Order | What to check | Command or file |
|---|---|---|
| 1 | Existing instance state | onstat - |
| 2 | Instance environment | GBASEDBTSERVER, ONCONFIG, GBASEDBTSQLHOSTS |
| 3 | Root database space | ROOTPATH in onconfig |
| 4 | File ownership and permissions | ls -l rootdbs |
| 5 | Network configuration | sqlhosts IP and port |
| 6 | Character set | Initialization configuration and data import test |
This sequence answers several questions in order:
- Does the target instance already exist and what is its current state?
- Is the current shell pointing to the correct instance?
- Can the configured root database space be accessed?
- Are remote connections configured correctly?
- Does the character set meet application requirements?
Each check can be verified independently.
7. Prevent Initialization Failures Before Running oninit
The five common problems have something in common: they can all be identified before or during the initial startup process.
Instead of memorizing error messages, move the checks earlier in the deployment workflow.
Before running oninit, verify:
- [ ] The
rootdbsdirectory and file exist. - [ ] Ownership and permissions are correct.
- [ ]
ROOTPATHpoints to the intended file. - [ ] All three environment variables reference the target instance.
- [ ]
sqlhostscontains the correct server address and port. - [ ] The character set matches the site requirements.
Initialization should be a controlled operation, not an experiment repeated until it succeeds.
Conclusion: Check the Environment Before Repeating Initialization
Troubleshooting GBase Database(GBase 8s) startup failures is often less about understanding complicated error messages and more about checking basic configuration details in the correct order.
Incorrect file permissions, invalid ROOTPATH, inconsistent sqlhosts, wrong environment variables, and character set mismatches can all create avoidable deployment problems.
The most effective approach is to turn these checks into a standard pre-initialization checklist.
GBase Database initialization happens once, but the configuration baseline should be verified before that first startup.
A few minutes of upfront validation can save much more time than repeatedly troubleshooting a failed initialization.
