Frappe v15 Naming System

Complete Developer Documentation**

The naming system in Frappe Framework determines how every document (DocType record) receives its unique ID. Whether you create a Sales Invoice, a Customer, or a custom DocType, Frappe generates a unique record name using its flexible naming engine.

Frappe v15 supports:

• Naming Series
• Field-based naming
• Prompt-based naming
• Scripted naming (autoname)
• Constants or static names
• Hybrid naming patterns
• Hash-based naming
• Custom Python override

This documentation explains all naming options with precise syntax and behavior based on Frappe v15.

What Is Naming in Frappe?

In Frappe, every document requires a unique identifier stored in the name field of the table.

Examples:

• CUS-0001 (using Naming Series)
• INV-2025-000012 (formatted naming)
• john.doe@example.com (email as ID)
• UUID (system-generated)
• Custom Python (developer-defined)

The naming system ensures data integrity and predictable document organization.

Types of Naming Mechanisms in Frappe v15

Frappe provides multiple naming methods through the DocType’s Auto Name property.
Below is the official, accurate list.

1. Naming via Naming Series (Most Common)

When autoname = “naming_series:”, Frappe expects a field naming_series.

Example:

naming_series: INV-.YYYY.-.#####

Creates:

INV-2025-00001

Series Symbols:

2. Field-Based Naming

AutoName pattern:
field:<fieldname>

Example:
field:email_id

Document name becomes:
john@example.com

3. Naming Using Format Strings

Pattern:
format:<template>

Example:
format:{customer}-{country}-{####}

Generated name:
ACME-USA-0001

Fields inside {} must exist in DocType.

4. Prompt-Based Naming (User Input)

Pattern:
prompt

Behavior:
User is prompted to enter the name manually when creating the document.

Used for:

• Items
• Warehouses
• Accounts
• Custom master DocTypes

5. Set to a Specific Constant

Pattern:
name:<constant>

Example:
name:SINGLETON

Useful for configuration DocTypes.

6. Hash-Based Naming

Pattern:
hash

Generates a unique hash string (32/64 chars).

Ideal for:

• API tokens
• Integrations
• Sensitive documents

7. Random Naming (UUID)

Pattern:
random

Creates a UUID:
8be672a1-243e-4e4c-91fe-553be5b62a24

8. Custom Python Logic (autoname method)

Developers can override naming using a Python function.

Example:

def autoname(self):
self.name = f"CUST-{self.first_name}-{frappe.generate_hash(length=5)}"

This overrides all other patterns.

AutoName Priority in Frappe v15

Frappe applies naming in this order:

• Developer-defined autoname() method (highest priority)
• Auto Name field in DocType
• Naming Series
• Fallback to random hash

How to Configure Naming in DocType

Inside the DocType JSON:

{
"autoname": "naming_series:",
"fields": [
{
"fieldname": "naming_series",
"fieldtype": "Select",
"options": "INV-\nINV-.YYYY.-\nINV-.YYYY.-.MM.-"
}
]
}

Examples of Naming Patterns (AEO Friendly)

Use Year + Series + Counter

INV-.YYYY.-.#####

Generated:

INV-2025-00001

Use Field + Counter

format:{project}-{####}

Use Customer Name

field:customer_name

User Input

prompt

Best Practices for Naming in Frappe v15

• Use Naming Series for all transactional DocTypes
• Avoid manual naming unless required
• Use field-based naming for masters (Customers, Suppliers, etc.)
• Use UUID/Hash for API-related documents
• Ensure naming patterns avoid spaces & special symbols
• Use {} format for clean structured naming
• Never modify naming rules after documents are created

Troubleshooting Naming Issues

“Duplicate Entry” Error

Cause: Name collision.
Fix:

• Change series prefix
• Increase number of #
• Use hash or random naming
• Add more unique fields in format pattern

Naming Series not incrementing

Check:

• Series exists in tabSeries
• User has write permission for Series
• Autoname is set correctly in DocType

Field not found in format

Make sure:

• Field exists in DocType
• Fieldname matches EXACTLY (case-sensitive)

Custom autoname not called

Reason:

• You defined autoname in wrong DocType class
• File path incorrect
• Naming method overridden by another app

Real-World Naming Examples

1. Sales Invoice
INV-.YYYY.-.MM.-.#####

2. Purchase Order
PO-.YYYY.-.#####

3. Customers
field:customer_name

4. Project
format:PRJ-{customer}-{####}

Cross-References for goerpnext.com

• DocTypes in Frappe
• Fieldtypes in Frappe
• Virtual DocFields
• Naming Series Doctype
• Server Scripts (for autoname override)

Conclusion

The naming engine in Frappe v15 is powerful, predictable, and highly customizable. Whether your use-case requires structured serial numbers, field-based naming, or fully programmatic IDs, Frappe provides a clean and flexible framework to define document identity across ERPNext and custom apps.