Solving the 'resource_func' Mystery: How I Made Ballerina's Compiler More User-Friendly

oshi-git — Tue, 18 Nov 2025 16:04:26 +0000

title: Solving the 'resource_func' Mystery: How I Made Ballerina's Compiler More User-Friendly
published: true
description: A deep dive into improving compiler error messages in the Ballerina programming language - from identifying the issue to implementing a production-ready fix
tags: ballerina, opensource, compiler, developerexperience

Solving the 'resource_func' Mystery: How I Made Ballerina's Compiler More User-Friendly

When developers encounter compiler errors, clear and actionable error messages can mean the difference between quick resolution and hours of frustration. This is the story of how I improved the Ballerina compiler's error messaging system to provide better developer experience.

The Problem: A Cryptic Error Message

While exploring the Ballerina programming language, I encountered issue #43815 in the Ballerina GitHub repository. Developers were reporting a confusing compiler error that displayed:

error: this resource_func must return a result

The issue? resource_func isn't valid Ballerina syntax. The correct syntax uses two separate words: resource function. This seemingly minor discrepancy was causing significant confusion among developers, particularly those new to Ballerina's resource function paradigm.

Why This Matters

In enterprise software development, developer experience (DX) is paramount. Clear error messages:

Reduce debugging time
Lower the learning curve for new developers
Improve code quality by guiding developers toward correct implementations
Decrease support burden on development teams

For a cloud-native programming language like Ballerina, which emphasizes developer productivity, this error message was undermining one of its core value propositions.

Investigation: Diving Into the Compiler Architecture

Understanding the Codebase

The Ballerina compiler is a sophisticated multi-module system written in Java. My investigation began with systematic code navigation:

Identifying the error origin: Located the diagnostic error code BCE2095 associated with this message
Tracing the error flow: Found the error was triggered in ReachabilityAnalyzer.java during semantic analysis
Understanding the root cause: Discovered the issue at line 583-584

The Root Cause

The problematic code was deceptively simple:

this.dlog.error(closeBracePos, DiagnosticErrorCode.INVOKABLE_MUST_RETURN,
    funcNode.getKind().toString().toLowerCase());

The compiler was calling getKind().toString().toLowerCase() on function nodes. For resource functions, this returned the enum value RESOURCE_FUNC (with underscore), which was then directly inserted into the error message template:

invokable.must.return=this {0} must return a result

Result: "this resource_func must return a result" instead of "this resource function must return a result"

The Solution: Implementing Proper Function Kind Formatting

Design Considerations

As an enterprise-grade compiler, any modification needed to:

Maintain backward compatibility
Follow established code patterns
Be maintainable and extensible
Not impact performance
Handle all function types correctly

Implementation Strategy

I implemented a helper method to properly format function kind names for user-facing error messages:

private String getFunctionKindName(BLangFunction funcNode) {
    String kind = funcNode.getKind().toString().toLowerCase();
    // Convert internal enum representation to user-friendly format
    if (kind.equals("resource_func")) {
        return "resource function";
    }
    return kind;
}

Then modified the error logging call:

// Before
this.dlog.error(closeBracePos, DiagnosticErrorCode.INVOKABLE_MUST_RETURN,
    funcNode.getKind().toString().toLowerCase());

// After  
this.dlog.error(closeBracePos, DiagnosticErrorCode.INVOKABLE_MUST_RETURN,
    getFunctionKindName(funcNode));

Why This Approach Works

Separation of concerns: Internal representation (RESOURCE_FUNC) remains unchanged while user-facing text is formatted appropriately
Extensibility: Easy to add formatting for other function types if needed
Minimal footprint: Single helper method, no changes to diagnostic infrastructure
Zero performance impact: Simple string comparison executed only during error conditions
Maintainability: Clear, self-documenting code that future contributors can easily understand

The Contribution Process

Technical Workflow

Contributing to a major open-source project requires following established protocols:

Forked the repository: Created personal fork of ballerina-platform/ballerina-lang
Created feature branch: fix-issue-43815 for isolation
Made targeted changes: Modified only ReachabilityAnalyzer.java
Committed with proper messaging: Clear commit message referencing the issue
Submitted Pull Request: #44407
Signed CLA: Completed Contributor License Agreement

Code Review Considerations

The PR includes:

Minimal diff: Only 13 lines changed, 5 removed
Clear intent: Single responsibility - fix error message formatting
No breaking changes: Backward compatible modification
No new dependencies: Uses existing infrastructure

Impact and Results

Immediate Benefits

Before:

error: this resource_func must return a result

Developers confused by non-existent resource_func syntax

After:

error: this resource function must return a result

Clear indication of correct syntax with two words

Broader Implications

This fix demonstrates several software engineering principles:

User-Centric Design: Error messages should use language users understand
Attention to Detail: Small UX improvements compound over time
Systematic Debugging: Methodical code navigation yields results
Clean Implementation: Simple solutions are often the best

Technical Learnings

Compiler Architecture Insights

Working with the Ballerina compiler provided valuable insights:

Semantic Analysis Phase: Error detection happens after parsing, during semantic analysis
Diagnostic System: Centralized error message management through property files
AST Traversal: Visitor pattern used for analyzing Abstract Syntax Trees
Error Reporting: Separation between error detection and message formatting

Best Practices in Large Codebases

Contributing to enterprise software taught me:

Read before you write: Understanding existing patterns prevents technical debt
Follow established conventions: Consistency matters in team environments
Document your reasoning: Clear commit messages and PR descriptions facilitate review
Test thoroughly: Even small changes need verification
Engage with the community: Responsive communication speeds up acceptance

Why This Matters for Developer Experience

The Cost of Poor Error Messages

Research shows that developers spend approximately 50% of their time debugging. Unclear error messages:

Increase time-to-resolution
Create frustration and cognitive load
May cause developers to abandon a technology
Generate unnecessary support requests

The Value of Continuous Improvement

Every error message improvement:

Saves collective developer hours
Improves language adoption
Demonstrates project maturity
Builds community confidence

Conclusion

Improving developer experience isn't always about major features or performance optimizations. Sometimes, it's about the small details - like ensuring error messages use the correct terminology.

This contribution to Ballerina demonstrates that open source is accessible to developers at all levels. You don't need to implement complex algorithms or major features to make meaningful contributions. Sometimes, the most valuable improvements are the ones that reduce friction in daily development workflows.

Key Takeaways

Start with good first issues: They're marked as such for a reason
Understand before you code: Time spent reading code is time well invested
Think about the user: Every message, error, or log is communication
Small PRs get merged faster: Focused changes are easier to review
Documentation matters: Well-documented contributions get better reception

Get Involved

Interested in contributing to Ballerina? Here's how to start:

Explore the codebase: github.com/ballerina-platform/ballerina-lang
Check good first issues: Look for beginner-friendly contributions
Join the community: Discord | Twitter
Read the docs: ballerina.io/learn

Every major open-source project started with someone's first contribution. This was mine - what will yours be?

About the Author

I'm a software engineering student passionate about compiler design, developer tools, and open-source contributions. This article documents my first contribution to the Ballerina programming language. Connect with me on GitHub.

Pull Request: #44407 - Fix error message for resource functions

Found this helpful? Follow me for more articles on open-source contribution, compiler design, and developer tools.

Ballerina #OpenSource #CompilerDesign #DeveloperExperience #SoftwareEngineering

Update: Code Review Journey

After publishing this post, the Ballerina maintainers provided excellent feedback during code review. The final merged version included additional improvements:

Better code formatting and indentation
More robust test cases using actual error scenarios
Cleaner method structure

This review process taught me the importance of code quality and responding to feedback professionally. The final PR was merged after 3 rounds of review!

View the merged PR here

Forem: oshi-git

Solving the 'resource_func' Mystery: How I Made Ballerina's Compiler More User-Friendly

Solving the 'resource_func' Mystery: How I Made Ballerina's Compiler More User-Friendly

The Problem: A Cryptic Error Message

Why This Matters

Investigation: Diving Into the Compiler Architecture

Understanding the Codebase

The Root Cause

The Solution: Implementing Proper Function Kind Formatting

Design Considerations

Implementation Strategy

Why This Approach Works

The Contribution Process

Technical Workflow

Code Review Considerations

Impact and Results

Immediate Benefits

Broader Implications

Technical Learnings

Compiler Architecture Insights

Best Practices in Large Codebases

Why This Matters for Developer Experience

The Cost of Poor Error Messages

The Value of Continuous Improvement

Conclusion

Key Takeaways

Get Involved

Ballerina #OpenSource #CompilerDesign #DeveloperExperience #SoftwareEngineering

Update: Code Review Journey