Java環境でCassandra Single-Nodeが起動しないときの徹底対策

はじめに (対象読者・この記事でわかること)

この記事は、Javaでバックエンド開発を行っているエンジニアや、ローカル環境・開発サーバー上でCassandraのシングルノードクラスタを構築しようとしたが起動できないと悩んでいる方を対象としています。
JavaのJDKが正しくインストールされている前提で、Cassandra のインストール直後に 「node1 does not appear to be up」 などのエラーメッセージが出るケースを想定しています。本記事を読むことで、

Cassandra が起動しない典型的な原因（Java バージョン不整合、環境変数、設定ファイルエラー、ポート競合など）を把握できる
cassandra.yaml や jvm.options のチェックポイントを具体的に確認できる
ログの解析手順と、実際に起きたエラー例に対する対処法を実装できる

といったスキルが身につき、ローカル開発環境の構築・トラブルシューティングがスムーズに行えるようになります。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。

Java（JDK8 以降）の基本的なインストールと JAVA_HOME の設定
Linux（Ubuntu/Debian 系）または macOS のターミナル操作
基本的な Cassandra の概念（ノード、キー・スペース、CQL）とインストール手順

Cassandra が起動しない原因と概要

Cassandra は Java で実装された分散データベースであり、起動時に JVM の設定や OS のリソース制限、設定ファイルの整合性が厳密にチェックされます。シングルノード構成でも、以下のような要因が起動失敗につながります。

カテゴリ	主な要因	影響
Java バージョン	JDK 11 以上が必要だが、JDK 8 しかインストールされていない	JVM の互換性エラー、`UnsupportedClassVersionError`
環境変数	`JAVA_HOME` が未設定、または `PATH` に正しい java が入っていない	`java: command not found`
ポート競合	9042（CQL）や 7000（内部通信）が既に別プロセスで使用中	`Address already in use`
ファイル権限	`cassandra.yaml` や `data/` ディレクトリの権限が不足	`Permission denied`
設定ミス	`endpoint_snitch` の不正値、`listen_address` が `localhost` でない	ノードが自分自身を見つけられず起動失敗
OS リソース	`vm.max_map_count` が不足、`ulimit -n` が低すぎる	メモリマッピング失敗、ファイルハンドル不足

これらはインストール直後に見落としがちですが、Cassandra の起動ログ（system.log と debug.log）に明確なヒントが出てくることが多いです。次節では、実際に起きた典型的なエラーパターンを例に、段階的に原因を切り分ける手順を紹介します。

具体的な手順とトラブルシューティング

以下の手順は、Ubuntu 22.04 または macOS（Homebrew）でのシングルノードインストールを想定しています。全ステップを順に実行し、各段階でログを確認しながら進めてください。

ステップ1：Java 環境の確認と整備

インストール済み JDK のバージョン確認
bash java -version Cassandra 4.x 系は JDK 11 以上が必須です。もし JDK 8 しか無い場合は、以下でインストールします（Ubuntu の例）。 bash sudo apt update sudo apt install openjdk-11-jdk
JAVA_HOME と PATH の設定
bash echo "export JAVA_HOME=$(readlink -f /usr/bin/java | sed 's:/bin/java::')" >> ~/.bashrc echo "export PATH=\$JAVA_HOME/bin:\$PATH" >> ~/.bashrc source ~/.bashrc
JVM オプションの確認
conf/jvm.options に -Xmx や -Xms が過度に大きく設定されていないかチェックし、メモリ 2GB 未満のマシンでは -Xmx2G → -Xmx1G に調整します。

ステップ2：Cassandra 設定ファイルのチェック

cassandra.yaml の重要項目
- cluster_name（任意の名前で OK）
- listen_address と rpc_address → ローカルホストの場合は localhost、外部からアクセスする場合は実 IP
- endpoint_snitch → SimpleSnitch がシングルノードには最適

bash grep -E 'listen_address|rpc_address|endpoint_snitch' conf/cassandra.yaml

データディレクトリの権限
bash sudo chown -R $(whoami):$(whoami) /var/lib/cassandra sudo chmod -R 755 /var/lib/cassandra
ポート使用状況の確認
bash sudo lsof -i :9042 sudo lsof -i :7000 競合があれば、該当プロセスを停止するか、cassandra.yaml のポート番号を変更します。

ステップ3：OS リソース制限のチューニング

Cassandra が大量のメモリマッピングを行うため、Linux の vm.max_map_count を 65535 以上に設定する必要があります。

Bash

sudo sysctl -w vm.max_map_count=262144
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf

また、ファイルディスクリプタ数 (ulimit -n) を 10000 以上に引き上げます。

Bash

ulimit -n 10000
echo "ulimit -n 10000" >> ~/.bashrc

ステップ4：Cassandra の起動とログ確認

Bash

sudo service cassandra start   # systemd が利用できる場合
# もしくは
bin/cassandra -f

起動直後に system.log と debug.log（/var/log/cassandra/ または conf/ 配下）をリアルタイムで確認します。

Bash

tail -f /var/log/cassandra/system.log

よく見られるエラーメッセージ例と対処

エラーメッセージ	原因	解決策
`java.lang.UnsupportedClassVersionError`	JDK バージョンが古い	JDK 11 以上へアップデート
`java.io.IOException: Permission denied`	ディレクトリ権限不足	`chown`/`chmod` で Cassandra ディレクトリの所有者を変更
`Address already in use (BindException)`	ポート競合	競合プロセス停止または `cassandra.yaml` のポート変更
`Failed to start up native transport (com.datastax.driver.core.exceptions.TransportException)`	`listen_address` が不正	`listen_address` を `localhost` または正しい IP に修正
`Error opening/creating file /var/lib/cassandra/data`	ディスク容量不足	ディスクをクリーンアップ、またはデータディレクトリを別領域に変更

ハマった点やエラー解決

ケーススタディ①：JDK 8 が残っていて java -version が 8 と表示された
インストール手順通りに JDK 11 を入れたものの、/usr/bin/java がシンボリックリンクで JDK 8 を指していました。
解決策：update-alternatives を使いデフォルト Java を切り替え、JAVA_HOME を再設定した。

Bash

sudo update-alternatives --config java
# 11 系のパスを選択

ケーススタディ②：vm.max_map_count がデフォルト 65530 のままで起動失敗
ログに Cannot allocate memory と出力され、java.lang.OutOfMemoryError が頻発。
解決策：/etc/sysctl.conf に vm.max_map_count=262144 を追記し、sysctl -p で反映。その後再起動で正常に起動。

まとめ

本記事では、Java 環境下で Cassandra Single-Node が起動しない 典型的な原因と、その対処手順を体系的に解説しました。

Java バージョンと環境変数の正しい設定 が最優先
設定ファイル(cassandra.yaml) の項目確認 と ポート・権限チェック が必須
OS リソース制限 (vm.max_map_count、ulimit) を適切にチューニングすることで、起動失敗の多くは回避できる

これらを実践すれば、ローカル開発環境での Cassandra の起動障害を迅速に解決でき、Java アプリケーションとの統合テストをスムーズに進められるようになります。今後は マルチノード構成へのスケールアップ や CQL スクリプトの自動デプロイ といったテーマで、さらに深掘りしていく予定です。

参考資料

Apache Cassandra 公式ドキュメント – Installation Guide
Cassandra 4.x のシステム要件とチューニングガイド
OpenJDK 11 リリースノート
Linux の vm.max_map_count 設定方法 (RedHat Docs)
「実践Cassandra入門」(著者: 小林真) – 第3章「トラブルシューティング」

Java環境でCassandra Single-Nodeが起動しないときの徹底対策💻