はじめに

Databricks AI Dev KitのBuilder Appは、Claude CodeのAgent SDKをバックエンドに持つフルスタックWebアプリケーションです。Databricksワークスペース上のDatabricks Appとしてデプロイするだけでなく、ローカルで起動して開発・デモに使うことも想定されています。

本記事では、Builder Appをローカルで起動する際に遭遇した既知の問題と、それらを回避して確実に起動するための手順をまとめます。

Builder Appのアーキテクチャ

Builder Appはバックエンド(FastAPI)とフロントエンド(React/Vite)の2プロセス構成です。データベースにはDatabricksのLakebase(PostgreSQL互換)を使用します。

バックエンド: http://localhost:8000(uvicorn)
フロントエンド: http://localhost:3000(Vite dev server)
データベース: Lakebase(Databricksワークスペース上)

start_local.sh というスクリプトが用意されており、Lakebaseのプロビジョニングから依存関係のインストール、環境変数の設定、サーバーの起動までを一括で行います。

遭遇した問題

問題1: Lakebaseプロジェクトの競合エラー

症状

start_local.sh のStep 3で以下のエラーが発生します。

Error: terraform apply: exit status 1
Error: failed to create postgres_project
  with databricks_postgres_project.builder_db,
project with such id already exists in the workspace

原因

スクリプト内部でTerraformが databricks_postgres_project を新規作成しようとしますが、同じIDのLakebaseプロジェクトが既にワークスペースに存在する場合に失敗します。一度でもスクリプトを実行してLakebaseが作成された後、2回目以降の実行やTerraformのstateが失われた場合に発生します。

databricks bundle destroy を実行してもTerraformのstateに該当リソースが存在しないため、同じエラーが繰り返されます。

回避策

Lakebaseプロジェクトを事前にワークスペースUIで作成しておき、--skip-lakebase と --lakebase-id を指定してスクリプトを実行します。

./scripts/start_local.sh --profile <your-profile> --skip-lakebase --lakebase-id <your-lakebase-id>

問題2: ENABLED_SKILLSのパス不整合(最も影響が大きい)

症状

バックエンド(uvicorn)の起動時に以下のエラーが発生し、アプリが起動しません。

server.services.skills_manager.SkillNotFoundError: Skill 'agent-evaluation' not found.
Directory does not exist: .../databricks-skills/agent-evaluation.
Check ENABLED_SKILLS in your .env file.

原因

start_local.sh のStep 7は以下の流れでスキルを処理します。

install_skills.sh を実行してスキルを .claude/skills/ にインストール
.claude/skills/ と databricks-skills/ の両方をスキャンし、SKILL.md があるディレクトリ名を収集
収集したスキル名を .env.local の ENABLED_SKILLS に書き込む

しかし、ランタイムの skills_manager.py はスキルの実体を databricks-skills/ のみから読み込みます。MLflow系スキル(例: agent-evaluation, instrumenting-with-mlflow-tracing)は install_skills.sh によって .claude/skills/ にはダウンロードされますが、databricks-skills/ には存在しません。

スキャン場所と実行時の参照場所が一致していないのが根本原因です。

特に、以前にClaude Code用のセットアップで install_skills.sh を同じリポジトリ配下で実行していた場合、.claude/skills/ に多数のスキルが残っているため、ほぼ確実にこの問題が発生します。

さらに厄介なことに、start_local.sh を実行するたびに ENABLED_SKILLS が上書きされるため、毎回手動でのクリアが必要です。

この問題についてはGitHub Issueを作成しました: Issue #465

回避策

.env.local の ENABLED_SKILLS を空にします。

sed -i '' 's/^ENABLED_SKILLS=.*/ENABLED_SKILLS=/' .env.local

問題3: Address already in use

症状

バックエンドを起動しようとすると以下のエラーが出ます。

ERROR: [Errno 48] Address already in use

原因

start_local.sh がバックエンドの起動に失敗した場合でも、プロセスが残ったままになることがあります。ソケットが CLOSED 状態のままポートを占有し続けます。

回避策

lsof -ti:8000 | xargs kill -9 2>/dev/null; true
lsof -ti:3000 | xargs kill -9 2>/dev/null; true

確実に動く起動手順

上記の問題を踏まえた、1パスで通る手順です。

前提条件

Node.js 18以上
npm
uv(Pythonパッケージマネージャー)
Databricks CLI v0.287.0以上(認証済みプロファイル設定済み)

初回セットアップ

1. リポジトリのクローンと移動

git clone https://github.com/databricks-solutions/ai-dev-kit.git
cd ai-dev-kit/databricks-builder-app

2. Lakebaseプロジェクトの事前作成

ワークスペースのUIまたはDatabricks CLIでLakebaseプロジェクトを事前に作成してください。start_local.sh 内のTerraformによる自動作成は競合エラーで失敗するリスクがあるため、事前作成して --skip-lakebase で起動する方が確実です。

3. アプリの初回起動

手順2で作成したLakebaseプロジェクトのIDを --lakebase-id に指定し、--skip-lakebase を付けて実行します。

./scripts/start_local.sh --profile <your-profile> --skip-lakebase --lakebase-id <your-lakebase-id>

初回実行でスクリプト内部で .env.local が自動生成されます。バックエンドが SkillNotFoundError で起動に失敗する場合は、Ctrl+Cで停止して次の手順に進みます。

4. ENABLED_SKILLSをクリア

databricks-builder-app ディレクトリで以下を実行します。

sed -i '' 's/^ENABLED_SKILLS=.*/ENABLED_SKILLS=/' .env.local

5. バックエンドとフロントエンドを起動

# ポートが占有されている場合はクリア
lsof -ti:8000 | xargs kill -9 2>/dev/null; true
lsof -ti:3000 | xargs kill -9 2>/dev/null; true
sleep 2

# バックエンド起動
uv run uvicorn server.app:app --reload --port 8000 --reload-dir server &

# フロントエンド起動
cd client && npm run dev &
cd ..

6. 動作確認

ブラウザで http://localhost:3000 にアクセスしてアプリが表示されることを確認します。

2回目以降の起動

初回セットアップ完了後は start_local.sh を再実行する必要はありません。バックエンドとフロントエンドを直接起動するだけで動作します。

ただし .env.local の DATABRICKS_TOKEN はOAuthトークンのため有効期限があります(通常1時間程度)。トークンが切れた場合はサーバーを再起動する前にトークンを更新してください。

cd ai-dev-kit/databricks-builder-app

# ポートクリア
lsof -ti:8000 | xargs kill -9 2>/dev/null; true
lsof -ti:3000 | xargs kill -9 2>/dev/null; true
sleep 2

# バックエンド起動
uv run uvicorn server.app:app --reload --port 8000 --reload-dir server &

# フロントエンド起動
cd client && npm run dev &
cd ..

トークンの更新が必要な場合

NEW_TOKEN=$(databricks auth token --profile <your-profile> 2>/dev/null | python3 -c "import sys, json; print(json.load(sys.stdin).get('access_token', ''))")
sed -i '' "s|^DATABRICKS_TOKEN=.*|DATABRICKS_TOKEN=${NEW_TOKEN}|" .env.local

まとめ

Builder Appのローカル起動は start_local.sh 一発で完了するはずですが、現状では以下の隘路があります。

問題	影響度	回避策
Lakebase競合エラー	中	事前作成 + `--skip-lakebase`
ENABLED_SKILLSパス不整合	高	毎回手動クリア
Address already in use	低	プロセスkill

最も影響が大きいのはENABLED_SKILLSのパス不整合で、スキャン場所(.claude/skills/ + databricks-skills/)とランタイムの参照場所(databricks-skills/ のみ)が一致しないためにアプリが起動しません。この問題は GitHub Issue #465 として報告済みです。

2回目以降の起動では start_local.sh を使わず、uvicorn と npm run dev を直接実行する方がトラブルが少なくおすすめです。

はじめてのDatabricks

はじめてのDatabricks

Databricks無料トライアル

Databricks無料トライアル