USING PYCFORGE

Fixing conversion errors

A diagnostic identifies the source that could not convert and explains why. Start with the first error, make a focused correction, and convert again.

On this page
Find and fix the source · Typed variable and string errors · Other typed conversion errors · Set errors · File errors during conversion · Runtime value conversion diagnostics · Understand the result

Variables and strings · Functions and modules · Reading and writing files

Find and fix the source

The amber warning-triangle button beside Tools opens a quick list of conversion diagnostics after a rejected or failed conversion. Each row shows the same severity, code, source location and message as the Diagnostics tab. Click a row, or select it and press Enter, to open its module and highlight the reported source. Long messages have full tooltips; rows without a source location cannot navigate.

Editing either Python view immediately closes this list and disables the button. Renaming or closing source, changing the bundle, or starting another conversion also retires old navigation. Undoing an edit does not re-enable old diagnostics: convert again. Switching tabs alone keeps current diagnostics available. This shortcut does not change the Diagnostics tab or run a Python code scan.

Select the diagnostic in the workspace to open its module and highlight the affected text.
Read the message and suggested correction. Keep the error code if you need to report the issue.
Compare your code with the matching example in Help.
Convert all included files again after editing. The old C output does not update until conversion succeeds.

Editor messages such as “search timed out,” “no definition found,” or a rename refusal belong to editing assistance. They do not decide whether Python can convert. See editor limits and completion and rename for those cases.

Typed variable and string errors

Code	Check this	Typical correction
`PYC4501`	Annotation and assigned value disagree.	Keep one type per variable. Use `1.0` for `float`; assign declarations before reading them.
`PYC4502`	A constant numeric value is unsupported or out of range.	Keep integer values within signed 64-bit limits and use finite floats.
`PYC4503`	A string contains NUL or cannot be encoded as valid UTF-8.	Use valid Unicode text without embedded NUL characters.
`PYC4504`	Constant expansion exceeded a conversion limit.	Reduce repetitions, expanded strings, or source size.
`PYC4505`	A constant string operation is invalid.	Check index bounds, slice steps, method arguments, and supported methods.
`PYC4506`	An assignment target or unpacking form is unsupported.	Use scalar names and matching flat tuple/list assignments; avoid nested or starred targets.
`PYC4507`	A module value needs unsupported runtime work or mutable state.	Use constant initializers, avoid conflicting names, and pass changing values as function parameters.
`PYC4510`	A string operation received a non-string value.	Keep both operands string-valued on every path.

Example: correct a typed assignment

rate: float = 1 assigns an integer to a float annotation and is rejected. Write a floating literal instead:

def doubled_rate() -> float:
    rate: float = 1.0
    return rate * 2.0

doubled_rate() returns 2.0. Changing an annotation alone does not convert an assigned value.

Other typed conversion errors

Code or family	Typical issue	Next step
`PYC100x`	Invalid conversion request or resource setting.	Try the default settings and check the requested limits.
`PYC28xx–PYC29xx`	Unsupported function, expression, call, return, or variable use.	Read the specific message and the matching reference page.
`PYC2940`	A variable may be read before assignment.	Initialize it before use on every continuing path.
`PYC2941`	A loop variable is used where it may not exist.	Initialize a separate result before the loop.
`PYC2943`	A variable changes type.	Use a consistent type in all assignments and branches.
`PYC34xx`	Unsupported container form or use.	Check Containers and records.
`PYC35xx`	Missing module, unsupported import, or conflicting name.	Add the required source file and use a direct function import.
`PYC36xx`	Unsupported record class, binding or field access.	Check the record binding examples and exact class rules. `PYC3623` identifies an invalid local record annotation or redeclaration.
`PYC9xxx`	Internal conversion error.	Save a minimal example, the exact message, and the installed version for a bug report.

Typed set errors

In Typed mode, use 1–64 unique literals of one numeric or Boolean type. Assign the set to a local name and use that name for membership checks. PYC3411 reports unsupported set indexing; PYC3412 reports unsupported set iteration. Use an ordered list or tuple when your program needs indexing or iteration.

File errors during conversion

Code	Typical correction
`PYC3901`	Use one direct function-body `with open` statement per session.
`PYC3902`	Do not reassign the built-in name `open`.
`PYC3903`	Check path, literal mode, `encoding='utf-8'`, and `newline=''`.
`PYC3904`	Give the handle a fresh local name.
`PYC3905`	Use one supported read or write and the documented return form.
`PYC3906`	Do not alias the handle or use it after the `with`; return a read value as documented.
`PYC3907`	Reduce the number of file operations.
`PYC3908`	In Typed mode, call file-access functions from C. Use Runtime for connected read/process/write functions.

Typed file errors when the generated C runs use numeric status values instead. See Check file errors from C.

Runtime value conversion diagnostics

Code	Meaning	Next step
`PYC4600`	Invalid Python syntax or a prohibited binding, such as duplicate parameter names.	Correct the indicated source location.
`PYC4601`	A source form, annotation, request combination, or syntax budget is outside the runtime conversion contract.	Check the runtime reference and use the complete runtime request options with all required companion documents.
`PYC4602`	Conversion encountered a resource limit.	Reduce the source size or nesting.
`PYC4610`	An import form is unsupported.	Use explicit named imports or module aliases; dotted import needs an alias.
`PYC4611` / `PYC4612`	The supplied module or declared member cannot be found.	Include the source and match its exact module ID and exported binding name.
`PYC4613` / `PYC4614`	The import budget is exceeded or a dependency cycle exists.	Reduce import items or move shared definitions into a dependency without back-imports.
`PYC4615`	A module initializer is not an admitted constant expression.	Use immutable scalar/tuple constants; put calls and mutable data inside functions.
`PYC4620`	A runtime open/context form is unsupported.	Use direct with open, an explicit UTF-8 encoding, a literal r/w/a mode, and the documented newline options. See file workflows.
`PYC4630`	An exception form is outside the Runtime profile.	Use unshadowed builtin handler names, omit exception-object bindings, and use literal raise messages. See Exceptions and cleanup.
`PYC4698`	Independent Runtime output/provenance validation failed; no new C output or mappings are published.	Keep the source and diagnostic for a converter issue report. This is an internal integrity failure, not a request to change valid Python. See Runtime validation.
`PYC4699`	The generated result uses the runtime value contract and carries information about its checks and code mappings.	Review the diagnostic and the runtime C caller requirements before using the output.

Duplicate bases, an inconsistent C3 order, or field/method name collisions produce PYC4601. Follow the source location and compare the hierarchy with Method order and super; reordering bases changes lookup behavior and should reflect the intended design.

Dynamic type errors, invalid arguments, out-of-range indices, arithmetic failures, and context-budget failures occur when generated C executes. They use context.error, context.error_source, and context.error_line, rather than a source-conversion diagnostic. Check the error, discard the failed result, and call pv_destroy.

Understand the result

Converted: C was produced for the complete submitted source.
Converted with warnings: C was produced; review every warning and the selected mode's caller requirements.
Rejected: correct the reported source issue; no new C is available.
Cancelled: conversion was stopped; start it again when ready.
Internal failure: record the error and a reproducible example.
Stale: the displayed C belongs to an earlier source or settings version. Convert again before saving it.

If a result includes warnings, review them before using the generated C.