エラーコードリファレンス

tdsl check / tdsl build / tdsl lint が出力する診断コードの一覧です。各コードの原因と修正方法を記載しています。症状からの切り分け方は Troubleshooting も参照してください。

パースエラー（E001–E008）

ファイルの構文解析中に発生するエラーです。.tdsl ファイルの記法が誤っている場合に報告されます。

コード	内容
E001	構文エラー
E002	整数変換エラー
E003	不明な再インポートポリシー
E004	不明な map ターゲット型
E005	予期しないルール
E006	不正な月/日
E007	不正な秒
E008	不正な UTC オフセット

E001: 構文エラー

メッセージ: Syntax error: ...

原因: DSL の文法に違反した記述があります。トークンの欠落、括弧の不一致、未知のキーワードなどが該当します。

修正方法: tdsl check / tdsl build はエラー行とその下にキャレット（^）でエラー箇所を強調表示します。表示位置を確認し、その記述を DSL 文法リファレンスと照合してください。

表示例（v1.14.0 以降: miette キャレット表示）

tdsl::parse_error

  × 構文エラー: expected EOI, timeline_block, lane_decl, ...
   ╭─[myfile.tdsl:1:1]
 1 │ xyzzy "bad" {
   · ┬
   · ╰── ここに問題があります
 2 │   title "T";
   ╰────
  help: DSL 仕様書 docs/dsl-spec.md を確認してください

# 誤り例
span dynasty { ... }   # laneキーワードより前にlane参照を置けない

# 正しい例
lane "王朝" as dynasty
span dynasty -206..-9 "秦" { ... }

E002: 整数変換エラー

メッセージ: Invalid integer at {location}: {value}

原因: 年数として解釈できない値が記述されています。

修正方法: 年数は整数で記述してください。紀元前は負数（例: -206）で表します。小数・文字列は使用できません。

# 誤り
span dynasty 200bc..0 "秦"

# 正しい
span dynasty -206..-9 "秦"

E003: 不明な再インポートポリシー

メッセージ: Unknown re-import policy: {value}

原因: import ブロックの on_reimport に指定したポリシー名が不正です。

修正方法: 使用できるポリシーは以下の 3 つです。

値	説明
merge_by_source	ソースが同じアイテムをマージ（デフォルト）
overwrite_imported	インポートアイテムを上書き
keep_manual	手動アイテムを優先して保持

E004: 不明な map ターゲット型

メッセージ: Unknown map target type '{value}' (expected one of: span, event, event_range)

原因: map <alias> to <target_type> { ... } の <target_type> に span / event / event_range 以外の値が指定されています。

修正方法: <target_type> は span・event・event_range のいずれかを指定してください（to の直後に置きます）。

# 誤り（timeline は target_type として無効）
map wd.han_dynasty to timeline {
    lane han;
}

# 正しい
map wd.han_dynasty to span {
    lane han;
    start claim(P571).year;
    end claim(P576).year;
}

target_type ごとの生成アイテム種別・必須プロパティは DSL 仕様書（本体リポジトリ docs/dsl-spec.md の map セクション）を参照してください。

E005: 予期しないルール

メッセージ: Unexpected rule {rule} at {location}

原因: パーサ内部で AST 変換中に予期しない構文ルールが検出されました。通常は発生しません。

修正方法: .tdsl ファイルを単純化して再現箇所を特定し、Issue に報告してください。

E006: 不正な月/日

メッセージ: Invalid month at {location}: {value} (expected 1-12) / Invalid day at {location}: {value} (expected 1-31)

原因: 時刻リテラル（YYYY-MM-DD / YYYY-MM-DDTHH:MM[:SS][±HH:MM]）の月が 1〜12、または日が 1〜31 の範囲外です。

修正方法: 月は 1〜12、日は 1〜31 の範囲で指定してください。カレンダーの対応日数チェック（うるう年等）は行わず、単純な範囲チェックのみです。

# 誤り
 event a 2024-13-01 "E" {};

# 正しい
event a 2024-12-01 "E" {};

E007: 不正な秒

メッセージ: Invalid second at {location}: {value} (expected 0-59)

原因: 時刻リテラルの秒部分（HH:MM:SS の SS）が 0〜59 の範囲外です（ADR 0003 D4）。うるう秒（leap second）はサポートしていないため 60 は常に拒否されます。

修正方法: 秒は 0〜59 の範囲で指定してください。

# 誤り
event a 2024-01-01T10:00:60 "E" {};

# 正しい
event a 2024-01-01T10:00:59 "E" {};

E008: 不正な UTC オフセット

メッセージ: Invalid UTC offset at {location}: {value} (expected Z or -14:00 through +14:00)

原因: 時刻リテラルのオフセット部分（Z または ±HH:MM）が不正です（ADR 0003 D4）。具体的には以下のいずれかです。

• 許容範囲 -14:00〜+14:00（実在する UTC オフセットの範囲）を超えている（例: +25:00）
• 書式不正（例: +09:3, +9:00）

修正方法: Z（UTC）または [+-]HH:MM 形式（例: +09:00, -05:00, +05:45）で、-14:00〜+14:00 の範囲内で指定してください。silent fallback（クランプや無視）は行わず、常にパースエラーとして拒否されます。

# 誤り（範囲外）
event a 2024-01-01T10:00+15:00 "E" {};

# 誤り（書式不正）
event a 2024-01-01T10:00+9:00 "E" {};

# 正しい
event a 2024-01-01T10:00+09:00 "E" {};
event a 2024-01-01T10:00Z "E" {};

意味エラー（E101–E113）

AST→IR 変換（lowering）フェーズで発生するエラーです。構文は正しくても意味的に矛盾がある場合に報告されます。

コード	内容
E101	未定義の lane 参照
E102	lane エイリアスの重複
E103	アイテム ID の重複
E104	timeline ブロックなし
E105	timeline ブロックの重複
E106	未解決の import 参照
E107	未解決のエンティティキー
E108	map が参照する lane が未定義
E109	テンプレートエイリアスの重複
E110	未定義のテンプレート参照
E111	不正なアイテム link URL
E112	不正なアイテム color 値
E113	UTC オフセット付き値となし値の比較

E101: 未定義の lane 参照

メッセージ: Unknown lane reference: {id}

原因: span / event / event_range で参照している lane ID が、lane 宣言で定義されていません。

修正方法: lane 宣言の as エイリアスと、アイテムの lane 参照が一致しているか確認してください。

検出タイミング: Wikidata フェッチ（import ブロックの解決）より前の lowering Pass 2 で検出されます。--offline フラグ不要でネットワーク接触前にエラーが報告されます。

# 誤り（"dynasty" が未定義）
span dynasty -206..-9 "秦"

# 正しい
lane "王朝" as dynasty
span dynasty -206..-9 "秦"

E102: lane エイリアスの重複

メッセージ: Duplicate lane alias: {id}

原因: 同じ as エイリアスを持つ lane 宣言が複数あります。

修正方法: 各 lane に一意のエイリアスを付けてください。

E103: アイテム ID の重複

メッセージ: Duplicate item id: {id}

原因: 同じ id を持つアイテムが複数定義されています。

修正方法: id はファイル内で一意にしてください。

# 誤り（id "qin" が重複）
span dynasty -206..-9 "秦" { id: qin }
span dynasty -206..-9 "秦（再掲）" { id: qin }

# 正しい
span dynasty -206..-9 "秦" { id: qin }
span dynasty -206..-9 "秦（再掲）" { id: qin_2 }

E104: timeline ブロックなし

メッセージ: No timeline block found

原因: ファイルに timeline ブロックがありません。

修正方法: ファイルの先頭に timeline ブロックを追加してください。

timeline {
  title: "私の年表"
  unit: year
  range: -500..2000
}

E105: timeline ブロックの重複

メッセージ: Multiple timeline blocks found

原因: timeline ブロックが 2 つ以上あります。

修正方法: timeline ブロックはファイルに 1 つだけ記述してください。

E106: 未解決の import 参照

メッセージ: Unresolved import reference: {key}

原因: map ブロック内で参照している wd.key が、対応する import ブロックで定義されていません。

修正方法: import ブロックのエイリアス名と map の参照名が一致しているか確認してください。

# 誤り（import のエイリアスが "emperors" なのに "emperor" を参照）
import Q7209 as emperors { ... }
map wd.emperor { ... }   # "emperor" は未定義

# 正しい
map wd.emperors { ... }

E107: 未解決のエンティティキー

メッセージ: Unresolved entity key: {key}

原因: map ブロック内で参照しているエンティティキーが、Wikidata から取得した結果に存在しません。

修正方法: tdsl fetch {QID} でエンティティの内容を確認し、存在するプロパティを使用してください。

E108: map が参照する lane が未定義

メッセージ: Map references unknown lane: {id}

原因: map ブロックの lane フィールドに指定した lane ID が定義されていません。

修正方法: E101 と同様に lane 宣言を追加するか、正しい lane ID を指定してください。

E109: テンプレートエイリアスの重複

メッセージ: Duplicate template alias: {id}

原因: 同じエイリアスの template 宣言が複数あります。

E110: 未定義のテンプレート参照

メッセージ: Unknown template reference: {id}

原因: apply で参照しているテンプレートが定義されていません。

E111: 不正なアイテム link URL

メッセージ: Invalid item link URL: {url} (expected http:// or https:// URL)

原因: link オプションに http:// / https:// 以外の URL（例: javascript:、data:、相対 URL）が指定されています。

修正方法: 参照 URL は絶対 URL で、スキームを http:// または https:// にしてください。

E112: 不正なアイテム color 値

メッセージ: Invalid item color value: {value}

原因: color オプションに安全な色値として扱えない文字列が指定されています。

修正方法: hex 色（#RGB, #RGBA, #RRGGBB, #RRGGBBAA）または単純な CSS 色キーワードを指定してください。

E113: UTC オフセット付き値となし値の比較

メッセージ: Cannot compare a UTC-offset time value with a value that has no offset (author must make both sides consistent): {0} vs {1}

原因: 同一の比較コンテキスト（例: 同一 span / event_range の start..end、同一 lane 内の並べ換え等）で、オフセット付きの時刻値（DateTimeOffset / DateTimeSecondOffset）とオフセットなしの時刻値（Year〜DateTimeSecond）を直接比較しようとしました（ADR 0003 D2）。

オフセットなしの値は「タイムゾーン不明」ではなく「タイムゾーンという概念を持たない裸の暦時刻」として扱われるため、暗黙に UTC とみなして正規化比較することはしません。Wikidata インポートは常にオフセットなし（DateTime / DateTimeSecond）で格納されるため、静的データにオフセットを付けた場合は Wikidata データと同一比較コンテキストで混在させるとこのエラーになりえます（意図した挙動）。

修正方法: 同一比較コンテキスト内の値は、全てにオフセットを付与するか、全てからオフセットを取り除くかで統一してください。Wikidata インポートと静的定義を同一 span / event_range で混在させたい場合は、静的側のオフセットを削除することでどちらもオフセットなしに揃えてください（本体リポジトリ docs/migration-second-precision.md の「Wikidataと静的offset付きデータの混在」節を参照）。

# 誤り（オフセット付きとなしが同一 span に混在）
span a 2024-01-01T10:00:00+09:00..2024-01-02T10:00 "S" {};

# 正しい（両方にオフセットを付与）
span a 2024-01-01T10:00:00+09:00..2024-01-02T10:00+09:00 "S" {};

# 正しい（両方からオフセットを除く）
span a 2024-01-01T10:00:00..2024-01-02T10:00 "S" {};

バリデーション警告（W201–W207）

IR 生成後の整合性チェックで発生する警告です。ビルドは続行されますが、出力が意図と異なる可能性があります。

コード	内容
W201	アイテムが未定義 lane を参照
W202	span の開始が終了より後
W203	timeline の range が不正
W204	lane の kind が未知の値
W205	Event が timeline.range 外
W206	Span / EventRange が timeline.range に完全に含まれない
W207	Span / EventRange が timeline.range を一部はみ出し（clipped）

W201: アイテムが未定義 lane を参照

メッセージ: Item references unknown lane: {lane}

原因: バリデーション段階で lane が見つかりません（通常は lowering で検出されます）。

W202: span の開始が終了より後

メッセージ: Span "{id}" has start ({start}) > end ({end})

原因: span の開始年が終了年より大きい値になっています。

修正方法: start..end の順に記述してください。tdsl lint --fix で自動修正できます。

# 誤り
span dynasty 9..-206 "秦"

# 正しい
span dynasty -206..9 "秦"

W203: timeline の range が不正

メッセージ: Timeline range is invalid: {start}..{end}

原因: timeline ブロックの range で開始が終了以上になっています。

修正方法: range: start..end の形式で start < end となるよう修正してください。

W204: lane の kind が未知の値

メッセージ: Lane "{id}" uses unknown kind: {kind} (known kinds: {known}; use custom for user-defined categories)

原因: lane の kind が既知値（custom / dynasty / person / country / event）のいずれにも一致しません。kind は自由分類の意図を持つためエラーにはしません。

修正方法: タイプミスでなければ無視して構いません。独自分類であることを明示したい場合は kind custom; を使ってください。

W205: Event が timeline.range 外

メッセージ: Event "{id}" at {time} is outside timeline.range and will not be rendered

原因: event の時刻が timeline.range の外にあります。Renderer は範囲外の Event を描画しません（以前は警告なしで無言 drop されていました）。

修正方法: timeline.range を拡大するか、意図的に表示範囲を絞っている場合は警告を無視して構いません。

W206: Span / EventRange が timeline.range に完全に含まれない

メッセージ: {Span|EventRange} "{id}" is entirely outside timeline.range and will not be rendered

原因: span / event_range の期間が timeline.range と一切重なっていません。

修正方法: timeline.range を拡大するか、アイテムの日付を見直してください。

W207: Span / EventRange が timeline.range を一部はみ出し（clipped）

メッセージ: {Span|EventRange} "{id}" is partially outside timeline.range and will be clipped

原因: span / event_range の一部のみが timeline.range 外にはみ出しています。意図的な表示範囲の絞り込みであれば無視して構いません。

修正方法: 意図した上であれば対応不要。タイプミスであれば timeline.range またはアイテムの日付を修正してください。

Lowering 警告（W208–W211）

lowering / validate 段階で発生する警告です。エラーではないためビルドは続行しますが、UTC オフセットの有無が食い違っていて前後関係を判定できないケースや、map / apply の解決結果に関わる問題を検知するために報告されます。tdsl build / tdsl check が Warning: として stderr に出力します。

コード	内容
W208	アイテムの時刻でオフセット付き値となし値が混在
W209	timeline.range でオフセット付き値となし値が混在
W210	マッピング対象が必須フィールド未解決でアイテム未生成
W211	offline lowering で import / map / apply が未解決

W208: アイテムの時刻でオフセット付き値となし値が混在

メッセージ: {Span|EventRange|Event} "{id}" mixes a UTC-offset time value with a value that has no offset; cannot determine start/end order (ADR 0003 D2, make both sides consistent)

原因: 1 つのアイテムの中で、UTC オフセット付きの時刻とオフセットなしの時刻が混ざっています。オフセットなしをどのタイムゾーンとみなすかは決まっていない（暗黙に UTC とはみなさない）ため、前後関係や範囲内かどうかを判定できません。

修正方法: 両方にオフセットを付けるか、両方から外して表記を揃えてください。lowering 側の同種エラーは E113 です。

W209: timeline.range でオフセット付き値となし値が混在

メッセージ: Timeline range mixes a UTC-offset time value with a value that has no offset; cannot determine range coherence (ADR 0003 D2, make both sides consistent)

原因: timeline の range の始点と終点で、UTC オフセットの有無が食い違っています。

修正方法: W208 と同じく、両端の表記を揃えてください。

W210: マッピング対象が必須フィールド未解決でアイテム未生成

メッセージ:

• Mapped entity {id} produced no item: required lane is unresolved/empty
• Mapped entity {id} produced no item: required label could not be resolved
• Mapped entity {id} produced no span: start/end could not be resolved
• Mapped entity {id} produced no event: time could not be resolved
• Mapped entity {id} produced no event_range: start/end could not be resolved

expand 使用時は {id} に (プロパティ#インデックス) が付与され、どの statement が解決できなかったかを示します（例: Q7209 (P39#2)）。

原因: 指定した claim(...) がエンティティに存在しない、対象言語の label が無い、lane プロパティが未指定、などにより必須値が None になっています。

修正方法: マッピング式（claim(P...).year 等）のプロパティ番号を確認し、?? でフォールバックを与えるか、label@en 等の取得言語を追加してください。対象エンティティが本当にその情報を持たない場合は map 対象から除外します。

W211: offline lowering で import / map / apply が未解決

メッセージ: {N} import block(s) and {M} map block(s) were not resolved (offline lowering); run 'tdsl build' without --offline to fetch Wikidata and validate imported items

原因: tdsl check（および tdsl build --offline）は lowering の Pass 1/2 のみを実行し、import 解決（Pass 3）と map 適用（Pass 4）を行いません。そのため import / map / apply ブロックから生成されるはずのアイテムは 0 件になります。

修正方法: エラーではありません。Wikidata 由来のアイテムまで検証したい場合は --offline を付けずに tdsl build を実行してください。

Wikidata エラー（E301–E307）

Wikidata API との通信・データ解析で発生するエラーです。

コード	内容
E301	HTTP 通信エラー
E302	不正な入力
E303	エンティティが見つからない
E304	時間値のパースエラー
E305	クレームが存在しない
E306	タイムアウト
E307	レート制限

E301: HTTP 通信エラー

メッセージ: HTTP error: ...

原因: Wikidata API への HTTP リクエストが失敗しました。ネットワーク障害・DNS 解決失敗などが原因として考えられます。

修正方法: ネットワーク接続を確認してください。開発中は --offline フラグで Wikidata アクセスをスキップできます。

tdsl build examples/my.tdsl --offline

E302: 不正な入力

メッセージ: Invalid input: {detail}

原因: QID やプロパティ ID の形式が不正です。

修正方法: QID は Q123 形式、プロパティ ID は P569 形式で記述してください。

E303: エンティティが見つからない

メッセージ: Entity not found: {id}

原因: 指定した QID のエンティティが Wikidata に存在しません。

修正方法: tdsl fetch {QID} または Wikidata（wikidata.org）で QID を確認してください。

E304: 時間値のパースエラー

メッセージ: Failed to parse time value: {value}

原因: Wikidata の API 応答に含まれる時間値を年数に変換できませんでした。

修正方法: tdsl fetch {QID} でそのエンティティのプロパティを確認し、時間値が存在するか確認してください。非常に古い年代（数万年前以前）は変換できない場合があります。

E305: クレームが存在しない

メッセージ: Missing claim {property} on entity {entity}

原因: map ブロックで参照したプロパティ（claim(P569).year など）がエンティティに存在しません。

修正方法: tdsl fetch {QID} でエンティティの利用可能なプロパティを確認してください。

tdsl fetch Q7209 --lang ja

E306: タイムアウト

メッセージ: Wikidata API request timed out. Try running with the --offline flag.

原因: Wikidata API へのリクエストが時間内に完了しませんでした。

修正方法: しばらく待ってから再実行してください。開発中は --offline フラグを使用してください。

E307: レート制限

メッセージ: Wikidata API rate limit exceeded (HTTP 429). Please wait a moment and retry.

原因: 短時間に大量のリクエストを送信したため、Wikidata API にレート制限されました。

修正方法: 数分待ってから再実行してください。多数のエンティティをインポートする場合は、--offline でまず静的アイテムを確認し、最終確認時のみオンラインビルドをすることを推奨します。

Lint コード

tdsl lint が検出する品質上の問題です。--fix で自動修正できるものは各コードの本文に明記しています。

コード	内容
ERROR: unknown_lane	未定義の lane 参照
ERROR: empty_label	空ラベル
ERROR: invalid_tags	不正なタグ
ERROR: duplicate_id	ID の重複
ERROR: start_gt_end	開始・終了が逆転
ERROR: mixed_offset_range	片側だけ UTC オフセット付きで順序が決まらない
WARN: missing_id	ID なし
WARN: invalid_calendar_date	無効なカレンダー日付
WARN: unused_lane	未使用の lane

ERROR: unknown_lane — 未定義の lane 参照

メッセージ: unknown lane reference '{id}'

原因: アイテムが存在しない lane ID を参照しています。

修正方法: E101 と同様の対処をしてください。

ERROR: empty_label — 空ラベル

メッセージ: label must not be empty

原因: アイテムのラベルが空文字列です。

修正方法: アイテムに意味のあるラベルを付けてください。

ERROR: invalid_tags — 不正なタグ

メッセージ: tags contain empty elements / tags contain duplicated elements / tags contain empty and duplicated elements

原因: タグリストに空文字列または重複したタグが含まれています。

修正方法: tdsl lint --fix で自動修正されます。手動修正する場合は空タグ・重複タグを削除してください。

ERROR: duplicate_id — ID の重複

メッセージ: id '{id}' duplicates line {line}

原因: 同じ ID が複数のアイテムに使われています。

修正方法: E103 と同様に ID をユニークにしてください。

ERROR: start_gt_end — 開始・終了が逆転

メッセージ: span range is reversed: {start}..{end} / event_range is reversed: {start}..{end}

原因: 開始年と終了年が逆になっています。

修正方法: tdsl lint --fix で自動修正されます。

ERROR: mixed_offset_range — 片側だけ UTC オフセット付きで順序が決まらない

メッセージ: span range mixes a UTC-offset time value with one that has no offset; start/end order cannot be determined (ADR 0003 D2, make both sides consistent): {start}..{end}

原因: range の片側だけに UTC オフセットが付いています。オフセットなしの値をどのタイムゾーンとみなすかは決まっていないため（暗黙に UTC とはみなしません）、開始と終了の前後関係を判定できません。

修正方法: tdsl lint --fix では直せません（fixable: false）。順序が決まらないものを入れ替えても正しくはならないため、書き手が両側の表記を揃える必要があります。同じ状況を tdsl check（validate）は W208/W209 として報告します。

WARN: missing_id — ID なし

メッセージ: id is missing

原因: アイテムに id プロパティが設定されていません。ID がないと Wikidata 連携（map ブロック）やプログラム的な参照ができません。

修正方法: tdsl lint --fix でランダム ID が自動生成されます。意味のある ID を付けたい場合は手動で設定してください。

span dynasty -206..-9 "秦" {
  id: qin
}

WARN: invalid_calendar_date — 無効なカレンダー日付

メッセージ: Invalid calendar date: YYYY-MM-DD

原因: YYYY-MM-DD 形式の日付が実在しません。典型的なケースとして以下があります。

• 2月30日・2月31日（2月は28日または29日まで）
• 4月・6月・9月・11月の31日（これらの月は30日まで）
• 閏年でない年の2月29日（例: 1900-02-29、2021-02-29）

修正方法: 正しいカレンダー日付に修正してください。閏年は「4で割り切れる かつ（100で割り切れない または 400で割り切れる）」年です。2000-02-29 は有効、1900-02-29 は無効です。

# 誤り（2月は最大29日まで。2024年は閏年だが30日は存在しない）
event events 2024-02-30 "存在しない日付"

# 正しい
event events 2024-02-29 "2024年は閏年"
event events 2024-03-01 "3月1日"

備考: パーサは日付の値域（月は 1〜12、日は 1〜31）のみを検証します。カレンダー上の実在確認（うるう年判定・月末日確認）は lint の責務です。月精度のみの指定（例: 2024-02）は検証対象外です。

WARN: unused_lane — 未使用の lane

メッセージ: lane '{id}' is declared but never referenced (it renders as an empty band)

原因: lane ブロック（group 内も含む）で宣言された lane が、span / event / template / apply / map のいずれからも参照されていません。参照されない lane はレンダリング結果で空の帯になります。

修正方法: tdsl lint --fix では自動修正されません（これから item を追加する予定で先に宣言したケースを壊さないため）。不要であれば lane 宣言を削除し、必要であれば参照するアイテムを追加してください。

関連ドキュメント

• DSL 文法リファレンス — 文法の詳細
• クイックスタート — 基本的な使い方
• Troubleshooting — 症状からの切り分け