目次
「kintoneへの自動登録を作ったら、エラーで1件も入らない」——外部システムやGAS（Google Apps Script）からkintoneにデータを書き込む連携で、よく出会うのがGAIA_LO03というエラーです。
画面から手で入力しているときは何の問題もなかったアプリなので、多くの場合「プログラムのどこかがおかしい」と考えて、コードの見直しから始めてしまいます。ところが原因はコードではなく、アプリの設定にあります。
この記事では、GAIA_LO03が起きる原因と、コードを書き直さずに解消する対処、そして連携を作り始める前に決めておきたい確認の順番を整理します。
この記事の結論
- GAIA_LO03はルックアップのキー設定が原因で起きる
- 参照先のキー項目に重複禁止を設定すれば解消する
- 外部から書き込む設計の前にキー項目を必ず確認する
GAIA_LO03エラーとは
GAIA_LO03は、kintoneにAPI経由で書き込んだときに、ルックアップ項目が原因でレコードを登録できない場合に返ってくるエラーです。
ルックアップは、別のアプリ（参照先アプリ）のデータを、キーになる項目で引いてくる仕組みです。たとえば「顧客コード」をキーにして、顧客マスタから顧客名や住所を取り込む、といった使い方をします。
このルックアップを含むアプリに、外部からデータを入れようとしたときにGAIA_LO03が出ると、そのレコードは登録されません。連携の仕組み自体は動いているのに、肝心のデータが入らない状態になります。
なぜ画面入力では気づかないのか
厄介なのは、この問題が手入力の運用では表面化しないことです。現場の担当者が画面から入力しているうちは、何年使っていても気づかないことがあります。
エラーが初めて出るのは、外部システムやGASからの連携を作り込んだ段階です。
この順番で起きるため、担当者は自然と「新しく作った連携のコードが悪い」と考えます。アプリは今まで普通に使えていたのですから、疑う理由がありません。その結果、コードの書き方や送っているデータの形式を何度も見直すことになり、原因の切り分けに時間を取られるのです。
GAIA_LO03の原因：参照先キーの重複禁止設定
原因はひとつです。ルックアップの参照先アプリで、キーにしている項目に重複禁止の設定が入っていないことです。
kintoneのフィールド設定には「値の重複を禁止する」というチェック項目があります。ルックアップのキーとして使う項目にこれが設定されていないと、API経由の書き込みではGAIA_LO03になり登録できません。
| 状態 | 画面からの手入力 | API・GASからの書き込み |
|---|---|---|
| キー項目に重複禁止あり | 登録できる | 登録できる |
| キー項目に重複禁止なし | 表面上は問題が出ない | GAIA_LO03で登録できない |
つまり見るべき場所は、書き込み先のアプリではなく参照先アプリのキー項目です。ここを見落とすと、書き込み先のアプリやコードをいくら調べても答えにたどり着けません。
なお、kintoneの仕様は変わることがあるため、最新の挙動は公式のヘルプで確認してください。
GAIA_LO03の対策：コードではなくアプリ設定を直す
対処は、参照先アプリのキー項目に「値の重複を禁止する」を設定することです。コード側の再実装は不要です。
ここが大事なポイントです。原因が分からないまま「コードが悪い」と判断すると、書き込み方法を変えたり、ルックアップを使わない形に作り直したりと、本来いらない手戻りが発生します。アプリ設定を1か所直すだけで済む話が、開発のやり直しに膨らんでしまうのです。
設定を変える前には、参照先アプリのキー項目の値が、実際に一意になっているか（同じ値が重複して登録されていないか）を確かめておくと安心です。ルックアップのキーは、本来「1つの値で1件に決まる」ことが前提の項目だからです。
外部連携を設計する前の確認順
この件から持ち帰っていただきたいのは、個別のエラー対処よりも確認の順番です。kintoneへ外部から書き込む設計を始める前に、次の順で確認しておくと、GAIA_LO03で足止めされることはなくなります。
- ルックアップの有無を確認する：書き込み先のアプリに、ルックアップ項目が含まれているかを洗い出します。
- 参照先のキー項目を特定する：各ルックアップが、どのアプリのどの項目をキーにしているかを確認します。
- 重複禁止の設定を確認する：そのキー項目に「値の重複を禁止する」が入っているかを見ます。入っていなければ、先に設定を直します。
- 連携の実装に入る：アプリ側の前提が整ってから、GASや外部システムの実装を始めます。
ポイントは、コードを書く前にアプリ設定を確認するという順番を決めておくことです。エラーが出てから調べるのではなく、設計の段階でチェックリストに入れておけば、切り分けの時間そのものが発生しません。
よくある質問
Q. kintoneのGAIA_LO03エラーの原因は何ですか？ ルックアップの参照先アプリで、キーにしている項目に「値の重複を禁止する」が設定されていないことが原因です。この状態だと、API経由の書き込みではレコードを登録できずエラーになります。
Q. GAIA_LO03を直すにはプログラムの修正が必要ですか？ 基本的に不要です。参照先アプリのキー項目に「値の重複を禁止する」を設定すれば解消します。コードを疑う前にアプリ設定を確認するのが近道で、原因の切り分けにかかる時間も短くできます。
Q. 画面入力では問題ないのに、APIだとエラーになるのはなぜですか？ 手入力で運用しているうちはこの設定不足が表面化せず、外部システムやGASから書き込む連携を作った段階で初めてエラーとして現れるためです。今まで動いていたことは、設定が正しい証拠になりません。
まとめ
- GAIA_LO03は、ルックアップの参照先キー項目に重複禁止の設定がないと起きる
- 画面からの手入力では表面化せず、API・GAS連携を作った段階で初めて出る
- 対処は参照先アプリの設定変更で、コードの再実装は不要
- 外部から書き込む設計の前に、ルックアップのキー項目と重複禁止設定を確認する順番を決めておく
RENOYでは、kintoneと外部システム・GASの連携について、実装に入る前のアプリ設定の確認から伴走しています。「連携を作ったがエラーの原因が分からない」「これから自動登録を作りたいが、何を確認すればいいか分からない」という段階のご相談も歓迎です。まずはお気軽に無料個別相談（オンライン・60分）をご利用ください。サービス内容をまとめた資料は資料請求からご覧いただけます。