跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
数据与分析

frappe-errors-database

Use when handling database errors in Frappe/ERPNext. Covers DuplicateEntryError, LinkValidationError, MandatoryError, TimestampMismatchError, CharacterLengthExceededError, InReadOnlyMode, QueryTimeoutError, SQL injection errors, frappe.db.sql parameter format (% vs %s), get_value returning None, transaction deadlocks, MariaDB gone away, too many connections. Error-to-fix mapping for v14/v15/v16. Keywords: database error, DuplicateEntryError, TimestampMismatchError,, MariaDB error, MySQL error, column not found, table missing, duplicate entry, database crash. SQL injection, deadlock, MariaDB gone away, query timeout.

OpenAEC-Foundation · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-errors-database

技能说明


name: frappe-errors-database description: > Use when handling database errors in Frappe/ERPNext. Covers DuplicateEntryError, LinkValidationError, MandatoryError, TimestampMismatchError, CharacterLengthExceededError, InReadOnlyMode, QueryTimeoutError, SQL injection errors, frappe.db.sql parameter format (% vs %s), get_value returning None, transaction deadlocks, MariaDB gone away, too many connections. Error-to-fix mapping for v14/v15/v16. Keywords: database error, DuplicateEntryError, TimestampMismatchError,, MariaDB error, MySQL error, column not found, table missing, duplicate entry, database crash. SQL injection, deadlock, MariaDB gone away, query timeout. license: MIT compatibility: "Claude Code, Claude.ai Projects, Claude API. Frappe v14-v16." metadata: author: OpenAEC-Foundation version: "2.0"

Frappe Database Error Diagnosis & Resolution

Cross-ref: frappe-core-database (API syntax), frappe-errors-controllers (controller errors).


Error-to-Fix Mapping Table

Error / ExceptionHTTPCauseFix
DuplicateEntryError409Unique constraint violation on insert/renameCheck existence first OR catch and return existing
DoesNotExistError404get_doc() on missing recordUse frappe.db.exists() first OR catch exception
LinkValidationError417Link field points to non-existent recordValidate link target exists before save
LinkExistsErrorN/ADelete blocked by linked documentsShow linked docs to user; use force=True carefully
MandatoryError417Required field is empty on saveSet all mandatory fields before insert/save
TimestampMismatchErrorN/AConcurrent edit detected (modified changed)Reload doc and retry, or inform user to refresh
CharacterLengthExceededError417String exceeds field maxlength / DB column sizeTruncate input or increase field length
DataTooLongException417Value exceeds DB column storage capacitySame as CharacterLengthExceededError
InReadOnlyMode503Write attempted during read-only modeCheck frappe.flags.in_import or site config
QueryTimeoutErrorN/AQuery exceeded time limit [v15+]Add indexes, reduce result set, paginate
QueryDeadlockErrorN/ATwo transactions waiting on each otherRetry with backoff; reduce transaction scope
TooManyWritesErrorN/AExcessive writes in single requestBatch operations; use background jobs
InternalError (gone away)N/AMariaDB connection droppedReconnect with frappe.db.connect()
InternalError (too many)N/AConnection pool exhaustedCheck max_connections; close idle connections
ValidationError417General validation failure in saveRead error message; fix field values
SQL syntax errorN/AWrong frappe.db.sql() parameter formatUse %(name)s with dict, NOT %s with tuple

Exception Hierarchy

Exception
├── frappe.ValidationError (HTTP 417)
│   ├── frappe.MandatoryError
│   ├── frappe.LinkValidationError
│   ├── frappe.CharacterLengthExceededError
│   ├── frappe.DataTooLongException
│   ├── frappe.UniqueValidationError
│   ├── frappe.UpdateAfterSubmitError
│   └── frappe.DataError
├── frappe.DoesNotExistError (HTTP 404)
├── frappe.DuplicateEntryError (HTTP 409)  ← inherits NameError
├── frappe.TimestampMismatchError
├── frappe.LinkExistsError
├── frappe.QueryTimeoutError
├── frappe.QueryDeadlockError
├── frappe.TooManyWritesError
├── frappe.InReadOnlyMode (HTTP 503)
└── frappe.db.InternalError  ← MariaDB/Postgres driver error

frappe.db.sql() Parameter Format

# ❌ WRONG — %s with positional tuple (works but fragile)
frappe.db.sql("SELECT * FROM `tabItem` WHERE name = %s", ("ITEM-001",))

# ❌ WRONG — f-string or .format() — SQL INJECTION!
frappe.db.sql(f"SELECT * FROM `tabItem` WHERE name = '{item_name}'")
frappe.db.sql("SELECT * FROM `tabItem` WHERE name = '{}'".format(item_name))

# ❌ WRONG — bare % operator
frappe.db.sql("SELECT * FROM `tabItem` WHERE name = '%s'" % item_name)

# ✅ CORRECT — named parameters with dict (ALWAYS use this)
frappe.db.sql(
    "SELECT * FROM `tabItem` WHERE name = %(name)s AND warehouse = %(wh)s",
    {"name": item_name, "wh": warehouse},
    as_dict=True
)

# ✅ CORRECT — frappe.qb (query builder, no injection risk)
Item = frappe.qb.DocType("Item")
result = (
    frappe.qb.from_(Item)
    .select(Item.name, Item.item_name)
    .where(Item.warehouse == warehouse)
    .run(as_dict=True)
)

Rule: ALWAYS use %(name)s with a dict parameter. NEVER use string formatting for SQL values.


get_value Returns None: Not an Exception

# ❌ DANGEROUS — get_value returns None, not raises
credit = frappe.db.get_value("Customer", "CUST-001", "credit_limit")
if credit > 1000:  # TypeError: '>' not supported between NoneType and int
    pass

# ✅ CORRECT — handle None explicitly
credit = frappe.db.get_value("Customer", "CUST-001", "credit_limit")
if credit is None:
    frappe.throw(_("Customer not found"))
credit = credit or 0  # Default to 0 if field is empty

# ✅ CORRECT — get_value with as_dict for multiple fields
data = frappe.db.get_value("Customer", "CUST-001",
    ["credit_limit", "disabled"], as_dict=True)
if not data:  # None when record not found
    frappe.throw(_("Customer not found"))
if data.disabled:
    frappe.throw(_("Customer is disabled"))

Key behavior by method:

MethodRecord Not FoundEmpty Field
get_doc()Raises DoesNotExistErrorReturns field default
get_value()Returns NoneReturns None or ""
get_all()Returns []Included in result
exists()Returns FalseN/A
set_value()Silently does nothingN/A
db.sql()Returns [] or ()Included in result

Handling Each Exception Type

DuplicateEntryError

# 
阅读完整来源 ↗