5 Common GBase Database Cluster Installation Errors and How to Troubleshoot Them

GBase Database(GBase 8a) cluster installation errors can look unrelated, but many can be traced to five layers: SSH login, configuration parameters, node roles, operating system compatibility, and recovery procedures.

The fastest way to troubleshoot is to identify the failing stage, verify its prerequisites, and change one variable at a time. Repeatedly replacing packages or reinstalling the entire cluster can waste time and make the original problem harder to diagnose.

This guide covers five common GBase Database cluster installation problems, what to check first, and how to approach each one safely.

1. SSH Login Failure: Permission denied

Layer: Login and authentication

A message such as Fail to login ... Permission denied usually indicates that the installer cannot authenticate to a target host. Before changing the cluster configuration, verify the SSH port, account, authentication method, and network connectivity.

Common causes include:

• The actual SSH port differs from the value configured in demo.options.
• The dbaUser account cannot authenticate to the target node.
• SSH keys or their directory permissions are incorrect.
• Passwords containing special characters are handled incorrectly by the shell or installation script.
• SSH access was configured for root, but the installer connects as gbase.

Test connectivity using the same account and port that the installer will use:

ssh -p 22 gbase@192.168.146.20

Check the SSH server configuration on the target host, where permitted:

grep -E '^[[:space:]]*(Port|PermitRootLogin)' \
  /etc/ssh/sshd_config

Remember that the effective SSH configuration may also depend on included configuration files and other authentication settings.

Recommended fix: Make sure sshPort, dbaUser, and the actual authentication configuration agree. Test every target host from the initiating node before rerunning the installation.

2. Parameter Parsing Failure: invalid literal for int()

Layer: Configuration parameters

An error such as invalid literal for int() indicates that a value expected to be numeric could not be parsed as an integer. The cause is not necessarily a password: it could also be a malformed port, NodeID, or another parameter.

Start by identifying the exact parameter mentioned in the traceback or installation log.

Check for:

• Unexpected characters in numeric fields.
• Missing or extra delimiters in demo.options.
• Incorrect quotation marks or whitespace.
• Passwords containing shell-sensitive characters that may have been interpreted incorrectly.
• Hidden control characters introduced while editing or copying the file.

Inspect the relevant configuration lines and compare them with the template supplied with your installed GBase Database version.

Recommended fix: Correct the specific malformed value and validate the configuration before retrying. Do not weaken a production password to work around a parsing error. Use the documented escaping or credential-handling procedure for the installer.

3. GCware Registration Failure: fail to add new datanodes to gcware

Layer: Node roles and cluster configuration

This error can occur when the installation process reaches GCware registration but cannot complete the expected node operation.

One area to investigate is the relationship between the three host lists in demo.options:

• coordinateHost
• dataHost
• gcwareHost

Check that each host is assigned the intended role, that the IP addresses or hostnames resolve correctly, and that NodeIDs match the expected configuration.

Also verify that the affected node can communicate with the relevant cluster services and that GCware is operating as expected.

Recommended fix: Compare the configured host lists against the actual deployment plan. Then check the affected node's installation logs, network connectivity, and GCware status. Avoid editing multiple role assignments simultaneously, because that can make the original cause harder to identify.

4. Operating System Validation Failure

Layer: Platform compatibility

A message such as operating system is 'xxx', must be centos7 indicates that an installation prerequisite check rejected the detected operating system.

Do not assume this is merely a naming mismatch. First establish whether the target platform is actually supported by the selected package.

Check the kernel information:

uname -r

Also inspect the operating system release information:

cat /etc/os-release

Compare the results with the compatibility requirements for your GBase Database release and installation package.

Some installer versions provide options to bypass particular validation checks. However, bypassing a check does not make an unsupported operating system compatible.

Recommended fix: If the platform is supported but the installer misidentifies it, follow the documented workaround for that exact release. If the operating system or kernel is unsupported, use a compatible package or supported environment rather than forcing installation.

Only use an option such as -i when the version-specific documentation confirms its meaning and the reason for bypassing the check has been validated.

5. Reinstalling the Entire Cluster After One Node Fails

Layer: Recovery and change management

A failed node does not automatically mean the entire GBase Database cluster must be rebuilt.

First determine how far installation progressed, which nodes completed successfully, and whether the existing cluster remains in a supported operational state. Preserve the installation logs before attempting recovery.

For an established cluster, a documented node-addition procedure may use gcChangeInfo.xml and gcadmin addnodes. However, this is appropriate only when the cluster state, node condition, and release-specific procedure support adding the node.

A partially completed initial installation may require a different recovery process.

Recommended fix: Identify the failed stage, inspect the current cluster state, and follow the documented recovery or cleanup procedure. Avoid rebuilding healthy nodes unnecessarily, but do not assume that adding a node is always safe after a failed installation.

A Practical Troubleshooting Order

When GBase Database cluster installation fails, work through the layers in order:

1. Login: Verify SSH connectivity, authentication, account, and port.
2. Parameters: Inspect the exact configuration value associated with the error.
3. Roles: Validate host lists, NodeIDs, and GCware registration prerequisites.
4. System: Confirm operating system, kernel, architecture, and package compatibility.
5. Recovery: Decide whether to retry, repair, add a node, or perform a controlled cleanup.

These categories can overlap. For example, an SSH problem can prevent a node from completing GCware registration. Fix the earliest confirmed failure before changing later-stage configuration.

After resolving the issue, record the original error, its root cause, the corrective action, and the verification result in the deployment handover notes.

Final Thoughts

Most GBase Database(GBase 8a) cluster installation problems become easier to diagnose when the failing stage is isolated before changes are made.

Start with SSH access, validate the parameters, confirm node-role consistency, check platform compatibility, and choose a recovery procedure based on the actual cluster state.

The goal is not simply to get the installer running again. It is to identify the failed prerequisite and restore a deployment process that can be repeated reliably.

For parameter syntax, supported platforms, installer options, and node-recovery procedures, always consult the documentation for your specific GBase Database release.