Import Diagnostics & Error Codes

When you import an API specification, Aethrix analyses the document, generates typed C# classes for every operation, compiles them, and installs the result as an extension. Each of these stages can produce diagnostics — structured messages that tell you exactly what happened, where in your specification the problem is, and what to do about it.

This page explains how to read those diagnostics. For the import workflow itself, see Import API Specification.

---

Quickest Scenario

You import a specification and it fails:

1. The wizard's Analyze step shows a red summary — Specification has errors… — and blocks progression to naming. Fix what it reports before continuing.
2. If the failure happens later (at import), the Errors and diagnostics grid on the Results step lists every message.
3. Each row shows the message with its error code (OAS_FMT_001, CS0234, …) and, whenever Aethrix can locate it, the exact position in your specification — e.g. #/paths/~1pets/get/responses/200 or (Ln 42, Col 7).
4. Still stuck? Click Export diagnostics… and send the resulting ZIP to Aethrix support — it contains everything needed to reproduce the problem, with credentials removed.

---

Where Diagnostics Appear

Diagnostics can appear in two places:

Place	When
Analyze step (wizard step 3)	Immediately after locating the specification. Aethrix fetches and parses the document before asking for names, so most specification problems are caught here. Clicking Next > is blocked while errors remain.
Results step → Errors and diagnostics grid	During the full import (analysis + code generation + compilation).

Every diagnostic row contains:

Column	Description
Level	Icon: Information, Warning, or Error. Errors fail the import; warnings do not.
Message	The description, prefixed with its error code, plus the location in your spec when known.

Example rows:

[Error]   OAS_REF_001: Schema reference 'Pet' in #/paths/~1pets/get/responses/200
          is not defined in OpenAPI components/schemas. This reference will be skipped
          or treated as 'object'. Please verify your OpenAPI specification.
          Suggestion: Define the schema under components/schemas or fix the $ref target.
          at #/components/schemas/Pet (Ln 87, Col 11)
[Warning] OAS_DUP_001: Duplicate C# property name 'my_field' generated from JSON key
          'my-field'. Renamed to 'my_field_1'; the original name is preserved on the wire.

Tip: Messages are selectable text — select and copy them straight into your issue tracker.

---

Understanding Error Codes

Aethrix assigns a stable code to every diagnostic so you can search, filter, and discuss them unambiguously. Codes are prefixed by protocol family:

Prefix	Family
OAS_	OpenAPI / Swagger analysis
GQL_	GraphQL analysis
GRPC_	gRPC / Protobuf analysis
ASYNC_	WebSocket / AsyncAPI analysis
KAFKA_	Kafka Schema Registry analysis
CS…	C# compiler errors in generated code (Roslyn codes, see below)
AETH_GEN_* / AETH_COMPILE	Generic messages from other protocol analyzers that do not yet assign specific codes

OpenAPI codes (OAS_)

Format & reading

Code	Severity	Meaning	What to do
OAS_FMT_001	Error	The OpenAPI reader rejected part of the document (syntax error, invalid structure).	Fix the YAML/JSON at the reported location. Validate with Swagger Editor.
OAS_FMT_002	Error	The document could not be parsed at all — no usable specification was produced.	Check the file is valid YAML/JSON and matches OpenAPI/Swagger.
OAS_FMT_003	Error / Warning	Additional format problems detected during generation (some OAS2-only constructs are downgraded to warnings).	Same as OAS_FMT_001.

References

Code	Severity	Meaning	What to do
OAS_REF_001	Error	A local $ref points to a schema that does not exist under components/schemas.	Define the schema or fix the $ref target.
OAS_REF_002	Warning	The $ref points to an external file/URL, which is not loaded. The property is treated as an opaque value.	Inline the schema or import the referenced specification separately.
OAS_REF_003	Error	A $ref could not be resolved to any generated type; the property falls back to an opaque value instead of emitting broken code.	Usually follows OAS_REF_001 — fix the reference itself.

Schema constructs

Code	Severity	Meaning	What to do
OAS_SCH_001	Warning	A schema is empty or uses only unsupported constructs; the property becomes an opaque value.	Give the schema a type or properties if you want typed editing.
OAS_NOT_001	Warning	The JSON Schema not keyword is not supported; type resolution may be incomplete.	Re-express the constraint if the affected field matters.
OAS_UNION_001	Warning	A oneOf/anyOf mixing arrays of arrays falls back to object.	Simplify the union or handle the payload generically.
OAS_UNION_002	Warning	A oneOf/anyOf mixes incompatible scalar types (e.g. boolean and string). Aethrix cannot collapse it to one type without changing the wire format (a bare true vs a quoted "true"), so it is left as object.	Ask the spec author to pick one scalar type or add a discriminator.
OAS_UNION_003	Warning	A oneOf/anyOf has only unstructured members (type:object with no properties, type:array with empty items, bare type:string) — the union is really an "any JSON" constraint, not polymorphism. It is mapped to AnyJsonValue.	Paste any JSON as text. If the author meant a specific shape, define properties/items or add a discriminator.
OAS_UNION_004	Warning	A oneOf/anyOf of two or more inline object types (each declared inline, no $ref/allOf/array) with no discriminator cannot be dispatched — nothing on the wire selects a variant, and guessing a shape could pick the wrong type. It is mapped to AnyJsonValue.	Paste the exact JSON. For typed editing, ask the spec author to add a discriminator or make the variants share a common base.
OAS_DISC_001	Warning	A discriminator mapping entry references an unknown schema — polymorphic deserialization is incomplete for that value.	Add the referenced schema to components/schemas.
OAS_DISC_002	Info	A discriminator was detected and mapped.	No action needed.
OAS_DISC_003	Warning	A polymorphic oneOf/anyOf has no discriminator (or an incomplete one without a mapping) — nothing in the payload selects the variant. Aethrix synthesizes an editable type field with inferred per-variant values so sending and reading still work.	Test with the inferred values and correct them on the generated model if your server uses different ones. Or override the values at import time: the wizard's Discriminator Overrides step lets you assert the property name and per-variant values. Ask the spec author to add a discriminator block: a required propertyName plus a mapping from payload values to the variant schemas (OpenAPI §4.7.25).
OAS_DISC_004	Info	The undiscriminated union is provably dispatchable: every $ref variant declares a required property (own or inherited through allOf) that no other variant requires, so the read side selects the variant by payload presence; an ambiguous or non-matching payload stays raw JSON.	None — reading works without user input. Sending still uses the synthesized type field described in OAS_DISC_003.

Code generation

Code	Severity	Meaning	What to do
OAS_DUP_001	Warning	Two property keys normalize to the same C# name (e.g. my-field and my_field). One is renamed with [JsonProperty] preserving the wire name.	None — serialization is unaffected. Rename in the spec for cleaner classes.
OAS_ENUM_001	Warning	Two enum values normalize to the same C# member name; one is renamed with [EnumMember].	None — wire values are preserved.
OAS_ALLOF_002	Warning	allOf lists several $ref base types; C# has single inheritance, so extra parents are inlined as properties.	None, or flatten the composition in the spec.
OAS_ALLOF_003	Error	An extra allOf $ref could not even be resolved — its properties were omitted from the class.	Fix the unresolved reference.
OAS_DEF_001	Warning	A default value could not be represented in C#; the initializer was skipped.	None — requests just won't pre-fill that default.
OAS_META_001	Error	Operation metadata could not be generated for an operation.	Review the reported operation in the spec.
OAS_OP_001	Warning	Duplicate operationId; the later one was renamed with a _1 suffix.	Make operationIds unique in the spec.
OAS_OP_002	Warning	An operationId collides with a component schema name; the generated request class was renamed with a _Request suffix.	None. Rename the operationId in the spec for cleaner class names.
OAS_DUP_002	Warning	Two request parameters normalize to the same C# name (which would not compile); one is renamed with a numeric suffix while its wire name (query/header/path) is preserved by the location attribute.	None — requests are unaffected. Rename in the spec for cleaner classes.
OAS_CNT_001	Info	The request body declares multiple content types; only the highest-priority one is generated.	None, unless you need the other content types.
OAS_BASE_001	Info	No explicit Base URL was configured; the spec's first server entry is used.	None. Set a Base URL on the service if you need a different host.
OAS_BASE_002	Warning	The specification declares no servers, so the host it was imported from is used as the Base URL — scheme and host only, without the specification's own path.	None if that host is correct. Otherwise re-import and set Base URL on the wizard's naming step. A specification imported from a local file gets no guess; its operations have no endpoint unless you provide one.
OAS_SEC_001	Warning	The operation uses a security scheme Aethrix does not support yet.	Configure authentication manually on the service/environment.
OAS_RSP_001	Info	A response has neither headers nor a body schema; no response model was generated.	None. The raw HTTP response is still available.
OAS_GEN_500	Error / Warning	An unexpected internal error during code generation, or a schema that had to fall back to an opaque value to keep the code compilable.	Please report via a support bundle — this indicates an Aethrix bug.

Generated-code compiler errors (CS…)

When the generated C# fails to compile, rows carry real Roslyn codes such as CS0234 (type missing from namespace), CS0102 (duplicate member), or CS0542 (member named like its enclosing type). These almost always mean the specification triggers an Aethrix generator bug rather than a spec error — valid documents should never produce them.

If you hit one repeatedly:

1. Click Export diagnostics… — the bundle includes the generated sources so support can pinpoint the construct.
2. As a workaround, try renaming the offending schema/property in the spec (colliding names are the usual trigger).

Other protocols

Code	Severity	Meaning
GQL_SYN_001	Error	The GraphQL SDL failed to parse; the parser reports the line/column.
GRPC_PROTO_001	Error	protoc rejected the .proto file(s); the compiler's own file:line:col errors are shown.
GRPC_PROTO_002	Warning	A message about google/protobuf/…: either an import of it failed (reported together with GRPC_PROTO_001), or the standard message types were resolved from a folder that carries its own copy of them instead of the set shipped with Aethrix. The import itself normally succeeds.
GRPC_PROTO_003	Warning	The import succeeded, but the files declare protobuf constructs Aethrix does not generate or does not honour, listed with counts: group fields (proto2's pre-nested-message syntax: Aethrix refuses to send or receive one, with an error naming the field, and everything else in those files still works), extend declarations that add a field to a message and extensions N to M ranges (those fields are neither sent nor read) — options declared via extend google.protobuf.*Options, which is what most specs use, are not reported: they add no wire field, and field_behavior is read rather than ignored, enums with option allow_alias = true (aliased values may collapse), required fields with a declared [default = …] (always on the wire, so they go as the type's zero rather than the declared value), and deprecated services or RPC methods (callable as always, but the operation list cannot mark them yet). A [default = …] on an optional field needs no action: the field is left off the wire and the server applies its own default. Deprecated fields, messages and enum values are no longer listed here — they carry the same marker OpenAPI uses, so the tree shows them and they still work. Everything else in those files works.
GRPC_PROTO_004	Error	The import never reached the compiler: so many .proto files were passed at once that the command line outgrew what the operating system allows. Nothing was analyzed. Import the subdirectory holding the service you need, or pick individual .proto files instead of the whole tree. The message names the file count and the measured length.
ASYNC_YAML_001	Error	The AsyncAPI document could not be read or parsed.
KAFKA_SCH_001	Error	A subject uses a schema type other than Avro/JSON/Protobuf; that topic is skipped.
KAFKA_UNION_001	Warning	An Avro union mixes incompatible member types (e.g. string and number, or records and scalars); the field is generated as object and accepts any JSON value.
KAFKA_DEF_001	Warning	A schema default cannot be represented in C# — not a declared enum symbol, out of numeric range, or unparseable. The initializer was skipped; the CLR type default applies.
KAFKA_TOPIC_001	Warning	One Kafka topic failed to generate (an unexpected generator error); it was skipped and every other topic still imported.
ASYNC_MSG_001	Warning	One AsyncAPI message could not be parsed (an unexpected analyzer error); it was skipped and every other message still imported.
GQL_GEN_001	Warning	One GraphQL field (query or mutation) could not be generated (an unexpected generator error); it was skipped and every other field still imported.
GQL_GEN_002	Warning	The import produced no operations. The types were generated, but there is nothing to send: either the schema has no query root Aethrix can find (no type named Query, and no schema { query: … } block naming one), or that root declares no fields.
GQL_GEN_003	Warning	The document extends a type it never defines (extend type X with no type X anywhere in it), so the members that extension adds are not generated. Everything else imported.
GQL_GEN_004	Warning	Some field types were truncated by the introspection response: the endpoint answered with fewer levels of nesting than those types have, so what it did not describe cannot be typed. Those fields are left out of the generated queries (selecting them is what servers reject), and their properties on the generated classes hold editable raw JSON instead. The message names the fields.
GQL_GEN_005	Warning	One line per import listing what the schema declares and Aethrix does not honour, each with a count: custom scalars, mapped to text because only the server knows their format; types used but never defined in the document; and the distinct fields no generated query asks for, because a selection set stops two levels deep. When an interface is implemented by more types than one query can carry, the summary also names each such interface with how many of its implementors the generated query includes. Subscription fields generate operations like every other kind; when the schema declares them, the summary names the subscription root and counts its fields, as a reminder that these operations run as a stream over the graphql-transport-ws WebSocket transport rather than the HTTP POST the other operations use.
ODA_INIT_001	Error	The OData CSDL document could not be parsed — a document fault, fix the CSDL at the reported position.
ODA_VER_001	Critical	OData V2/V3 CSDL cannot be imported — an Aethrix limit, not a document fault; only OData V4 is supported.
ODA_SIZE_001	Critical	The CSDL exceeds the 1 MB conversion guard — an Aethrix limit; request a narrower $metadata endpoint (e.g. Microsoft Graph).
AETH_GEN_ERROR / AETH_GEN_WARN / AETH_GEN_INFO	varies	Generic message from an analyzer without a specific code yet.

Fetch and installation failures

Failures that happen around the document rather than inside it carry IMP_ codes, and each answers whose problem it is — that is what decides retry, fix or escalate:

Code	Whose problem	Meaning — and what to do
IMP_INPUT_001	Yours (the path)	The file or share does not exist. Verify the path.
IMP_NET_001	The network	Nothing answered — refused connection, TLS failure or timeout. Verify the address is reachable from this machine and check any proxy.
IMP_HTTP_001	The endpoint	Something answered with a non-success status that credentials will not change. Check that this URL really serves the description.
IMP_AUTH_001	Yours (the credentials)	The endpoint demanded or rejected credentials. Supply them, or export the specification and import from a file.
AETH_REG_001	Ours	No analyzer is registered for the requested type — an installation fault; report it.

Kinds and codes appear both in the diagnostics grid and, on failure, in the support bundle's diagnostics.json, so a report to support carries the attribution with the position.

---

Unsupported structures & fallbacks

This section is the single, exclusive reference for every schema construct that Aethrix deliberately degrades or rejects — with an example, Studio behavior, impact, likelihood in real public specs (measured on the 190-spec hardened corpus), and a tip. No other page duplicates it — protocol pages link here.

OpenAPI

OpenAPI is the most expressive format; most fallbacks keep the document importable. Likelihood is measured on the hardened corpus (100 OpenAPI specs + 90 cross-protocol specs).

Unsupported construct	Example	What you see in Studio	Impact	Likelihood in real specs	Tip
not keyword	not: {type: string}	Field stays editable but the exclusion is ignored	Small	Very rare (<1% — 0 in corpus)	Re-express as enum or pattern if the check matters
anyOf / oneOf mixing array and array of arrays	anyOf: [{type: array, items: {type: string}}, {type: array, items: {type: array}}]	Property becomes a generic value (accepts any JSON)	Small	Very rare (<1%)	Simplify the union or handle the payload as raw text
External $ref to another file/URL	$ref: '../common/Pet.yaml'	Field becomes generic (any value), warning OAS_REF_002	Medium	Occasional (~10–15% of public specs use shared files; apis.guru mirrors are inlined)	Inline the schema or import the referenced file separately
Empty schema (no type, no properties)	MyModel: {}	Field becomes generic (any value)	Small	Rare (~2%)	Add type: object + properties
discriminator mapping to unknown schema	discriminator: {propertyName: kind, mapping: {cat: '#/components/schemas/Cat'}} where Cat missing	Polymorphism for that value stays incomplete	Small	Rare (~2–3%)	Add the missing schema to components/schemas
allOf with several base $ref	allOf: [{$ref: '#/components/schemas/A'}, {$ref: '#/components/schemas/B'}]	Only the first base is inherited; others are copied as plain fields	Tiny	Occasional (~10% in large enterprise APIs)	Flatten the composition if inheritance matters
allOf base is a primitive/enum	allOf: [{type: string}, {properties: {x: {type: string}}}]	Properties are copied, no inheritance	Tiny	Rare (<5%)	—
Duplicate property keys after sanitizing	my-field and my_field in same object	One is renamed to my_field_1 (original wire name kept)	None	Rare (~2–3% — my-field/my_field collision seen once)	Rename in spec for cleaner names
Unknown format (uri-template, regex…)	type: string, format: uri-template	Treated as plain text	None	Rare (<2%)	—

SOAP

Unsupported construct	Example	What you see in Studio	Impact	Likelihood in real specs	Tip
One-way operation (no output message)	<operation name="notify"><input …/></operation>	You can still send; there is no typed response to assert	Tiny	Uncommon (~5% of WSDLs have notify/one-way; 0 in 7-spec corpus)	—
Type name equals service name (e.g. element Hello + port Hello)	portType name="Hello" + element name="Hello"	Studio renames the service contract behind the scenes; wire names stay intact	None	Rare (<2%)	—
Two different schemas define the same type name in one WSDL	Two complexType name="Address" in different namespaces	Later one is renamed to Address_2	Tiny	Rare (<2% — not seen in corpus)	Ask the WSDL author to rename one
Doubly-qualified type reference	— (importer artifact)	Collapsed automatically	None	Very rare (importer artifact)	—

OData

Unsupported construct	Example	What you see in Studio	Impact	Likelihood in real specs	Tip
OData V2 / V3 CSDL	DataServiceVersion="2.0" or 2007/06/edmx	Import blocked: OData V2/V3 is not supported…	High	High for legacy services (~40% of public OData samples still V2; V4 is current). Intentional: Microsoft.OData.Edm is V4-only	Re-export from a V4 $metadata endpoint
>1 MB CSDL (e.g. Microsoft Graph)	https://graph.microsoft.com/v1.0/$metadata (~1.8 MB)	Blocked before conversion: too large (1.8 MB; limit 1 MB)… Use a narrower $metadata endpoint	Medium	Rare but high-profile (only 1–2 massive models in 10-spec corpus; would OOM the converter)	Request a filtered $metadata (fewer entity sets)
Parse error (unknown attribute, bad XML)	ConcurrencyMode on V4 document	could not be parsed … (Ln 1, Col 2043)	Medium	Rare (<5% — strict XML)	Fix XML at the reported position

Kafka

Unsupported construct	Example	What you see in Studio	Impact	Likelihood in real specs	Tip
Avro protocol file .avpr	{"protocol":"BulkData","types":[…]}	Blocked: Avro protocol file (.avpr) is not supported…	Medium	Occasional (~15% of wiki examples show .avpr; production registries store .avsc)	Extract the types you need into separate .avsc files
Avro multi-type union (more than null + one type)	["string","int","null"]	Field becomes generic (any value)	Small	Rare (<3% — 1 in 17 corpus)	Restrict to ["null","string"] if possible
Avro unknown logicalType	logicalType: "custom-foo"	Falls back to base type (bytes, string…)	Tiny	Very rare (<1%)	—
JSON Schema oneOf (polymorphic)	oneOf: [{…}, {…}]	Field becomes generic (any JSON)	Small	Rare (<5%)	Use anyOf with a discriminator or a single concrete schema
JSON Schema external $ref	$ref: "https://other/pet.json"	Field becomes generic	Small	Rare (<5%)	Inline the schema
Protobuf Any / Empty	google.protobuf.Any	Field becomes generic (any value)	Small	Rare (<5% — fixed WKT Empty now maps)	Use a concrete message type
Protobuf Struct / ListValue	google.protobuf.Struct	Becomes Dictionary / List of generic values	Tiny	Rare	—

GraphQL

Unsupported construct	Example	What you see in Studio	Impact	Likelihood in real specs	Tip
Custom scalar	scalar DateTime	Field is edited as plain text, and the import names it in the GQL_GEN_005 summary	Tiny	Common — measured on the pinned corpus: 5 of the 11 endpoints that answered declare at least one (Json, BigDecimal, Cursor, Long, Time, Upload, CountryCode, FuzzyDateInt)	A value the server sends as a number or an object arrives as text; compare it as text in assertions
Selection depth cap	type A { b: B } where B has object fields of its own	A generated query asks two levels deep; fields below that are never selected, so their properties exist but stay empty. GQL_GEN_005 counts the distinct fields affected	Medium — the shape is imported whole, the data is not	Nearly every schema with nesting: 11 of the 13 endpoints in the pinned corpus, from 2 fields to 2 599 on the largest	Nothing to set at import time; the count tells you how much of a response will read as empty
Batched requests / file uploads	multipart/mixed	Not supported	Small	Rare (<5%)	Send one operation at a time
Introspection depth-limited gateway	countries.trevorblades.com	Studio automatically retries with a shallower query; fields the shallower answer could not describe are left out of the generated queries and named in a GQL_GEN_004 warning — their properties hold editable raw JSON, and the editor shows the warning when the operation is opened	Small — the rest of the schema imports and sends normally	Occasional (~20% of public endpoints gate depth)	Prefer providing an SDL file (.graphql)

gRPC

Unsupported construct	Example	What you see in Studio	Impact	Likelihood in real specs	Tip
map<K,V>	map<string, Foo> m = 1;	Shown as a dictionary editor (fully supported)	None	Very common (~60% of protos use map) — not a limitation	—
Well-known wrapper with oneof	oneof v { google.protobuf.DoubleValue x = 1; }	Correctly nullable (fixed from double??)	None	Rare (<5%) — now handled	—
Proto2 group	group Foo = 1 {…}	Field becomes generic	Tiny	Very rare (<1% legacy proto2)	Migrate to message (proto2 groups are obsolete)
Missing google/api or google/protobuf includes	import "google/api/annotations.proto" without an include path	Resolved automatically; file not found only if the file is neither shipped nor present in your tree	None in practice	Occasional (~10% of specs ship without the includes) — google/protobuf/* resolves from the well-known-type sources shipped with Aethrix, google/api/* from a folder inside your own spec tree	Keep the imports; you do not normally need an include path
Your own copy of the standard message types	An include path you added contains google/protobuf/*.proto	Warning GRPC_PROTO_002 naming that folder — its copy answers the imports it is consulted for, so the generated types can differ from Aethrix's	Can change generated types and field coverage	Very rare, and only on request: a path you typed wins by design so you can target a legacy service	Remove the vendored copy, or keep it deliberately and ignore the warning

WebSocket

Unsupported construct	Example	What you see in Studio	Impact	Likelihood in real specs	Tip
External $ref deeper than 16 levels / cycle	$ref: ./commons/a.yml → ./commons/b.yml → …	Reference kept as-is, reported as unresolved	Small	Very rare (<1% — depth guard triggers only on crafted/self-ref corpus broken-ext-ref-invalid)	Flatten the AsyncAPI file
AsyncAPI 3.0 operations without channels	operations: {sendX: {channel: {$ref: '#/channels/x'}}}	Resolved via channel lookup; missing channel → skipped	Small	Rare (<5%)	Ensure every operation references an existing channel
JSON-Pointer escape ~1 / ~0 in $ref	#/components/schemas/Foo~1Bar	Now decoded (~1→/) before resolve	None	Rare but now fixed	—
Self-referencing schema cycle	Node { child: Node }	Depth-guarded, degrades gracefully (generic fallback) rather than crash	None	Rare (corpus recursive-asyncapi) — now handled	—

---

Source Locations

Whenever Aethrix can locate a diagnostic in your specification, the message ends with its position:

• JSON Pointer — RFC 6901 paths like #/components/schemas/Pet/properties/id (~1 = /, ~0 = ~).
• Line/column — (Ln 42, Col 7) appended when the pointer could be matched against the document text. Works for JSON, YAML, XML (WSDL/CSDL), and GraphQL SDL.

Use these to jump straight to the offending spot in your editor — no more hunting through a 5,000-line spec.

---

Exporting a Support Bundle

If the import fails, the Results step offers Export diagnostics…. A review dialog lists exactly what will be packaged:

Content	Included	Notes
manifest.json	Always	Versions, service type, target namespace
diagnostics.json	Always	Options (credentials always redacted), logs, compilation errors, structured diagnostics
exception.json	Optional	Failure details; stack trace opt-in
spec/	Optional	The imported specification file(s)
generated-code/	Optional	The C# sources Aethrix generated
logs/	Optional	Analyzer and compilation logs

Review the list, adjust the checkboxes, then click Export… and choose where to save the ZIP. Nothing is sent automatically — you stay in control of what leaves your machine. Credential redaction is a locked guarantee: passwords, API keys and certificate data are removed no matter which options you pick. Note that specifications may contain internal hostnames — the dialog reminds you not to share bundles containing hosts you cannot disclose.

Command line

The CLI writes the same bundle on failure:

aeth analyze <spec-url> --type openapi ... --export-report ./bundles

• With a directory, the bundle is written as support-bundle-<timestamp>.zip inside it; with a file path, that file is written directly.
• Add --export-report-no-redact to keep credentials and stack traces for local debugging — DEBUG builds only; release builds ignore it and keep the bundle redacted.

---

Troubleshooting Quick Reference

Symptom	Likely cause	First step
Analyze step blocks immediately	Reader/format errors (OAS_FMT_*)	Fix the syntax at the reported line.
Fails with CS0234/CS0542/CS0102	Generator bug triggered by the spec construct	Export a bundle and report; try renaming the colliding schema.
Property appears as opaque/untyped	OAS_SCH_001, OAS_REF_002, OAS_REF_003	Resolve the reference or define the schema.
Missing operations after import	OAS_SEC_001, OAS_RSP_001, unsupported method	Check warnings; configure auth manually if needed.
Import cancelled	You clicked Cancel during import	Nothing was installed — simply start again.
gRPC import warns GRPC_PROTO_002 about a folder	That include path carries its own copies of the standard google/protobuf message types	Remove the path unless you are targeting a legacy service on purpose.
gRPC import warns GRPC_PROTO_002 about missing sources	The well-known-type files that ship with Aethrix are not beside protoc in your installation	Reinstall or update Aethrix; if it persists, export a bundle — a package built without them is an Aethrix bug.

---

Related

• Import API Specification — the full import workflow
• CLI Reference: analyze — all aeth analyze options