Importing Customers - Having Trouble Importing Customers and Related Data

ERPNext
1

I’m trying to import customers into ERPNext but keep running into vague errors that don’t provide any useful explanation.
A few of my errors

Or

  • Customer Primary Address: Value Company Namwe P O BOX A240 SWAZI PLAZA H100 Country Phone number missing for Address

Based on this GitHub issue, it looks like I need to import Contacts, Customers, and Addresses as separate entries. Can anyone confirm if that’s still the case?

Right now, I’m working on a local development server to figure things out before we move to the cloud version. I’m struggling because previous test imports are conflicting with new ones, and I’m not sure how to cleanly structure the import process.

Are there any in-depth guides for importing specific document types like Customers or Invoices? Most of what I’ve found just covers the basics of data import, but each document type has a huge number of fields and it’s not clear which are required or how they relate to each other.

Lastly, is there a recommended way to wipe all test data? I have a lot of junk data linked to Payments and Ledger Entries, and it’s preventing me from deleting things cleanly for a fresh start.

Any help would be appreciated. Thanks.

2

Update: Still No Progress, Serious Concerns

I ended up wiping the entire dev server and doing a fresh install to rule out any leftover data issues.

Even after that, the exact same problem happens, errors with no explanation, even when importing Contacts and Addresses first. There’s no clear direction on what order things need to be done in, and no documentation that actually walks through importing Contacts, Customers, or any specific document type, just a generic data import page that doesn’t help in real world cases.

There are multiple unanswered posts here and on GitHub about the same issue, some going back months or years. It feels like this problem is known but simply ignored.

At this point, I’m asking myself: is this really a platform I want to commit to?

3

Based on this GitHub issue , it looks like I need to import Contacts, Customers, and Addresses as separate entries. Can anyone confirm if that’s still the case?

Yes, and it will always be, preety logical isnt it?

I’m struggling because previous test imports are conflicting with new ones, and I’m not sure how to cleanly structure the import process.

So you will have to import them in phases. As is the case with most migrations and not just limited to this product. Complex software has complex structured data. You have to maintain the stucture and import them in phases.

Are there any in-depth guides for importing specific document types like Customers or Invoices? Most of what I’ve found just covers the basics of data import, but each document type has a huge number of fields and it’s not clear which are required or how they relate to each other.

I have not come across any, and dont expect it to show up any time soon. Because once you understand how the system works, these kind of questions will be answered on its own. Yes there are more meta fields that you see in the document. No one will have the time to write down what each field means and how it is used, not to mention how extensive the documents should be.

Lastly, is there a recommended way to wipe all test data? I have a lot of junk data linked to Payments and Ledger Entries, and it’s preventing me from deleting things cleanly for a fresh start.

There is no easy way to do this. Just dump the tenant/db and create it again, there is no other way.

Any help would be appreciated. Thanks.

Learn, slowly and stedily. Understand how data is structured. Only then will you understand how to import data in bulk.

There are multiple unanswered posts here and on GitHub about the same issue, some going back months or years. It feels like this problem is known but simply ignored.

Because no one is here to teach. You will have to learn on your own, just as everyone else does. And when you get stuck, ask the very specific question that is giving you trouble. Then you have a good chance of getting an answer. What you seem to expect (from what I can conclude) is that, you want a step by step guide to everything that is there on the platform. I can assure you, its not there and will not come about.

At this point, I’m asking myself: is this really a platform I want to commit to?

Let me give you an honest answer to this. → Thats for you to answer.
Because the community will not benefit with you being on board. It benefits if you contribute, and when both benefit from each other, its a match made it heaven. Thats the point of open source.

Here is my advice: Learn the system, manually, make all entries manually. then you will understand how they are linked. Once you enter everythign you will have a good grasp.

Now depending upon what kind of a user you are, either a developer or a enduser, choose your path.
If you are an end user, the manual approach works best for you. And if dont want spend the time doing so, it always makes sense to hire a consultant who will reduce the learning curve and make your life easier.
If you are a developer, the only way to learn is the hard way and jump right into the deep end of the pool and make sense of it all.

4

I expected there would at least be some explanation of the columns, especially when most imports involve multiple related tables behind the scenes.

Yesterday, my dev server ground to a halt. Imports simply stopped working. No errors, no notifications, just stuck in ‘Pending’ and never completed. No feedback, no logs.

Today I spent hours trying to get a basic list of customers in. I split it into three separate imports: Contacts, then Addresses, then Customers. Still got the same vague errors. At that point, I didn’t know what else to try, so I came back to this thread because I was completely stuck.

What’s really shaking my confidence is:

  • Imports that hang forever in ‘Pending’ with no indication of success or failure
  • No clear way to know what actually imported, and what didn’t

I get it, there are no docs to explain it.

5

Yesterday, my dev server ground to a halt. Imports simply stopped working. No errors, no notifications, just stuck in ‘Pending’ and never completed. No feedback, no logs.
Today I spent hours trying to get a basic list of customers in. I split it into three separate imports: Contacts, then Addresses, then Customers. Still got the same vague errors. At that point, I didn’t know what else to try, so I came back to this thread because I was completely stuck.

Welcome to software development. Nothing different that you would encounter trying to run software.

  • Imports that hang forever in ‘Pending’ with no indication of success or failure.
    *No clear way to know what actually imported, and what didn’t

These two points of yours are valid. The import tracker doesnt work properly. You will have to import in smaller batch sizes and check manually if the import is completed.

6

Welcome to software development. Nothing different that you would encounter trying to run software.

My plan was to use a local install to figure out the import process, then buy the cloud version and import all of our real data. But from what you’re saying, it’s normal, even expected for things to grind to a halt like this? Does that include the hosted paid version as well?

These two points of yours are valid. The import tracker doesn’t work properly. You will have to import in smaller batch sizes and check manually if the import is completed.

So there’s no documented row limit, and no real guidance on when an import will fail silently, just trial and error until it works? That’s frustrating when you’re dealing with real data and deadlines.

If that’s the case, then I genuinely think ERPNext needs to be more upfront about the limitations of the import tool. Right now it gives the impression of being production-ready

7

So there’s no documented row limit, and no real guidance on when an import will fail silently, just trial and error until it works? That’s frustrating when you’re dealing with real data and deadlines.

There will always be issues that you will come across, when dealing with software. And theses issues may not be documented. Its nothing new. I have dealt with software libraries that has absolutely zero lines in documentation, but is used widely. Simply because it works. Thats the reality of software, be prepared to read code and understand how things work.

What you are asking for, does not exist in real life. There is no enterprise software in this world, which will work perfectly. There will always be issues, and work around for those issues.
Existance of issues just means thats there are more pressing matters that the developers are looking into, that this doesnt make the priority list.

If that’s the case, then I genuinely think ERPNext needs to be more upfront about the limitations of the import tool. Right now it gives the impression of being production-ready

Btw the product is production ready. Thats why thousands of companies use it. Lets not blame ERPNext. You just need to put in more effort to learn how everything works.

Just to be clear I am not associated with ERPNext or Frappe in any way.

And let me also give you some ground reality on enterprise software, which I have dealt with for more than 2 decades. You can spend a million dollars on enterprise software, and it will give worse issues than this and you will have to beg the provider to get the issues fixed. Compared to what I have seen happen in real life, ERPnext is pretty neat.

8

It still does not help me know how I relate a customer to a contact and an address on an import. Guessing what the relation might be may be normal for the software you use but it is not for me.

I understand your standpoint, I just don’t agree with it. Your stand point makes me hesitant to come here for help.

I have other issues which may or may not be bugs, but from what you say I have to not only figure out by trail and error, but also consider it may be a bug.

Someone must have successfully imported a long list of customers with addresses and contacts and know how to do it, so the logical thing would be look at the docs, but from what you say you have to guess.

9

I understand your standpoint, I just don’t agree with it. Your stand point makes me hesitant to come here for help.

In this case, my standpoint, or rather my observations, evolving into conclusive opinions, is a reflection of human psychological behavior. Here it pertains to how an open source system is explored, used and modified for personal use.

ERPNext is an open source project. It enables a person like you and me to get ahead, without reinventing the wheel. But to put the car in motion is our responsibility.

I have other issues which may or may not be bugs, but from what you say I have to not only figure out by trail and error, but also consider it may be a bug.

Yes. now we are getting somewhere.

Someone must have successfully imported a long list of customers with addresses and contacts and know how to do it, so the logical thing would be look at the docs, but from what you say you have to guess.

Yes, thousands of companies have figured out how to do it. And are using ERPNext in their day to day operations. And then there are another thousand implementation companies who have used it to provide services to thousands of other companies.

That said, you dont need a team to figure out how the product works. Just some time and dedication. I dont think more than a dedicated week is needed.

10

This thread is really going off the rails.

Simple answers to your questions:

  1. To understand how tables are linked, check the doctype definition. You’ll be able to see the type of each field. Connections between tables are established by “Link Fields”. You can’t just provide arbitrary data to a link field. That data needs to exist in the linked table first. If it doesn’t exist, Frappe will throw the errors you are seeing.

  2. I’m not aware of any constraint on Import row size imposed by Frappe. If your imports are crashing, it’s very possibly a memory constraint or something else on the server side. These things are tricky to troubleshoot.

If the two things above are more than you are willing or able to manage, probably not.

11

Thanks for the direction. Where might I see the doc types? Searching for “doctype definition” yields no results. I have searched the documentation and the API docs for a list of table fields, but have no luck.

This is exactly the issue I am having. I do not know which field is the foreign key. Early on in my trial and error I found that Customer names were used as the key, this is a problem for me to use as I have multiple systems coming in with different db table shapes and I cannot rely on company names as the key, because people make spelling mistakes or drop in a parenthesis later which would break my intended API usage. I have defaulted to using uuids for the moment, but eventually we would like to use our own company codes.

Right now I am figuring out a migration plan from Sage Pastel and also other internal systems. I am using the open source docker install to do all of my testing and compile a load of working CSVs. Once I have this ready we will go with the paid cloud version and dump everything.

12

You can see them in the Frappe itself by going to the “DocType list” from the search bar.

Screenshot 2025-06-30 at 9.02.31 AM
Screenshot 2025-06-30 at 9.02.31 AM2140×1590 274 KB

You should see something that looks like this, and if you scroll to the bottom there will be a list of fields.

You can also view the doctype definition as a .json file in the source code, for example here:

Anything that shows "fieldtype": "Link" is going to be a foreign key.

13

Thank you so much. Having access to this part; I literally have most of the system figured out now. I have my price_lists, customers, items, item_prices customer addresses, contacts etc all coming in smoothly. Still a way to go with accounts and initial balances, but once we open up a cloud account we should be ready and loaded with a perfect set of CSVs to dump in and get going.

1 Like
14

In case you don’t know, there is “System Console” which you can find with the search bar an the Desk and which you might find useful. And there is a REST API for every Doctype, just search the documentation for it, e.g. you don’t need to pass via CSV imports, which allows you to feed data not as one big batch, but piecemeal, if you want. “Server Script” allows you to run data fetcher with cron. With “bench mariadb” you can also directly access the database and explore Doctypes from this perspective. It’s fun all this.