The Error That Made Me Question Everything

You know that moment when your code looks perfect, but your computer disagrees? I was there. Working on a blog system, feeling pretty good about myself, when Python decided to humble me:

1

Error: Unsupported type: ForwardRef('list[Comment]') on field 'comments' from class PostFactory.

My first thought: “But… Comment is RIGHT THERE! I can literally see it in my code!”

If you’ve ever stared at an error message that seems to defy the laws of reality, you know this feeling. Your class exists. You can point to it. You could print it out and tape it to your monitor if that would help. But Python acts like it’s playing hide and seek, and your Comment class is apparently really good at hiding.

Let Me Show You the Crime Scene

Here’s what my code looked like. See if you can spot the problem (spoiler: I couldn’t for hours):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

from __future__ import annotations
from typing import List
from pydantic import BaseModel
from polyfactory.factories.pydantic_factory import ModelFactory

# My main blog models - the stars of the show
class Post(BaseModel):
    title: str
    content: str
    comments: List[Comment]  # <- This innocent line caused all my pain
    author: Author          
    tags: List[Tag]         

class Author(BaseModel):
    name: str
    bio: str
    posts: List[Post]

# ... imagine 500 lines of other stuff here ...
# (authentication, database connections, that one function 
#  you wrote at 3 AM and are afraid to touch)

# Way down here, the supporting cast
class Comment(BaseModel):
    text: str
    author_name: str

class Tag(BaseModel):
    name: str
    color: str

# And then, in my test file:
def test_create_mock_post():
    factory = ModelFactory.create_factory(Post)  # 💥 KABOOM!
    mock_post = factory.build()

Look reasonable? That’s what I thought too.

My Journey Through the Five Stages of Debugging

Stage 1: Denial
“This must be a typo. Let me check… nope, Comment is spelled correctly everywhere.”

Stage 2: Anger
“Stupid polyfactory! It’s clearly broken!” (Narrator: It wasn’t broken.)

Stage 3: Bargaining
What if I:

• Update all my packages?
• Restart my computer?
• Try a different import style?
• Sacrifice my favorite coffee mug to the Python gods?

Stage 4: Depression
“Maybe I’m just not cut out for this. Maybe I should become a farmer.”

Stage 5: Acceptance… and then Confusion
“Wait, if I test just the Comment class by itself…”

1
2
3

def test_comment_alone():
    factory = ModelFactory.create_factory(Comment)  # This works perfectly!
    mock_comment = factory.build()

So Comment works fine on its own, but breaks when Post tries to use it? What kind of sorcery is this?

The Lightbulb Moment (That Should Have Been Obvious)

After hours of debugging, I realized something that’s both profound and embarrassingly simple: Python reads your file like a book - from top to bottom, line by line.

Think about it like this. Imagine you’re reading a mystery novel:

“The butler walked into the room where Colonel Mustard had been murdered.”

If you haven’t been introduced to Colonel Mustard yet, you’d be confused, right? You’d think, “Wait, who’s Colonel Mustard? Did I miss something?”

Python feels the same way. When it gets to line 10 and sees:

1
2

class Post(BaseModel):
    comments: List[Comment]  # Python: "Who's Comment? I haven't met them yet!"

But Comment isn’t introduced until line 501! Python is basically reading a story where the main character references someone who doesn’t appear until chapter 27.

“But Wait,” You Say, “My Code Runs Fine!”

Good observation! If Python reads top to bottom and doesn’t know what Comment is on line 10, why doesn’t it immediately crash when I run my program?

The answer is this sneaky little import at the top:

1

from __future__ import annotations

This line is like telling Python: “Hey buddy, when you see type hints, don’t worry about what they mean right now. Just treat them like strings. We’ll figure it out later.”

So when Python sees:

1

comments: List[Comment]

With __future__ annotations, it actually stores it as:

1

comments: "List[Comment]"  # Just a string! No need to know what Comment is yet

It’s like writing an IOU. Python says, “Okay, I’ll store this as a string now, and we’ll cash it in when we actually need to know what Comment is.”

When the IOU Comes Due

Here’s where things get spicy. Most of the time, these string annotations work great. Your code runs, type checkers are happy, life is good.

But then you use a tool like polyfactory. When you write:

1

factory = ModelFactory.create_factory(Post)

You’re essentially telling polyfactory: “Hey, I need you to create fake Post objects for testing.”

Polyfactory: “Sure! Let me see what a Post looks like…”

• title: str ✅ “I know what a string is!”
• content: str ✅ “Another string, easy!”
• comments: "List[Comment]" 🤔 “Hmm, this is just a string. Let me convert it to a real type…”

And this is where polyfactory tries to cash in that IOU. It looks for a class named Comment in the current environment. But here’s the thing - even though Comment is defined in your file, it hasn’t been executed yet because Python is still working through your file top to bottom.

It’s like trying to use a gift card for a store that hasn’t opened yet. The store will exist, but not right now when you need it.

What’s a ForwardRef Anyway?

When Python can’t find the actual class for a string annotation, it doesn’t just give up. It creates something called a ForwardRef - basically a fancy placeholder that says, “I promise this will be a real type eventually, I just don’t know what it is right now.”

Think of it like leaving a sticky note that says “TODO: Figure out what Comment is.” This works fine for most Python operations, but when a tool needs to actually CREATE Comment objects (not just know they’ll exist someday), that sticky note isn’t very helpful.

The Solution (So Simple It Hurts)

After all that investigation, the fix is almost comically simple. Just rearrange your classes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

from __future__ import annotations
from typing import List
from pydantic import BaseModel

# Define the supporting cast FIRST
class Comment(BaseModel):
    text: str
    author_name: str

class Tag(BaseModel):
    name: str
    color: str

# THEN define the main models that use them
class Post(BaseModel):
    title: str
    content: str
    comments: List[Comment]  # Now Python knows who Comment is!
    tags: List[Tag]         # And Tag too!

class Author(BaseModel):
    name: str
    bio: str
    posts: List[Post]       # Post is defined right above, so we're good

That’s it. Just put the classes that others depend on first. It’s like introducing all the characters before you start telling the story about them.

When Will This Bite You?

You might think, “Okay, interesting story, but will this ever happen to me?”

More often than you’d expect! This pattern shows up with:

1. Testing libraries that create fake data (like our friend polyfactory)
2. API frameworks that auto-generate documentation from your models
3. Database ORMs that need to understand relationships between your models
4. Serialization tools that convert your objects to/from JSON
5. Validation libraries that create validators on the fly

What do these all have in common? They need to actually understand and work with your types at runtime, not just store them for later.

A Quick Analogy

Think of Python’s execution model like building furniture from instructions:

Normal Python code is like IKEA instructions that say “Insert Piece A into Piece B” - it doesn’t matter if you haven’t unpacked Piece B yet, because you’re just reading the instructions.

Runtime type inspection is like having a robot that reads those same instructions and immediately tries to build the furniture. If Piece B is still in the box at the bottom of your pile, the robot’s going to have a problem.

The Bigger Picture

This whole adventure taught me something important: in Python, when you define something can matter just as much as how you define it.

Most programming languages are like recipes where you can list ingredients in any order. Python is more like a cooking show where you need to prep your ingredients in the order you’ll use them.

When Order Doesn’t Matter (So You Don’t Panic)

Just to be clear, this ordering issue ONLY affects runtime type inspection. These scenarios are totally fine:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# Type hints in functions - checked statically, not at runtime
def process_post(post: Post) -> None:
    pass  # Even if Post is defined later, this is fine

# Regular function calls - they run after everything is defined
def create_blog():
    post = Post(...)  # This runs when you call create_blog(), 
                      # by which time Post exists

# Method definitions
class BlogManager:
    def handle_post(self, post: Post):  # Totally fine
        pass

The Real Lesson Here

The next time you see a ForwardRef error, take a deep breath. It’s not your computer trying to gaslight you. It’s not a bug in the library you’re using. It’s probably just Python gently reminding you that it reads your code like a book - from start to finish.

The fix is usually dead simple: move your dependency classes to the top of the file. Your code will work exactly the same, but now tools that need to inspect your types at runtime will be happy.

And honestly? There’s something beautifully humbling about spending hours debugging what seems like a complex error, only to fix it by playing musical chairs with your class definitions. It reminds us that sometimes the most confusing problems have the simplest solutions.

One Last Thought

You know what’s funny? After figuring this out, I now instinctively put my “helper” classes at the top of my files. Not because I’m worried about forward references, but because it actually makes the code easier to read. You introduce the supporting cast before the main characters.

It’s like Python was trying to teach me good storytelling all along.

Have you ever been bitten by Python’s execution order? I’d love to hear your stories. Sometimes the best way to learn is by sharing our collective “I can’t believe it was that simple” moments.

P.S. - If you’re using polyfactory or similar tools, consider this your friendly reminder: those “helper” classes at the top of your file aren’t just good organization. They’re your insurance policy against future head-scratching.