hyperledger/fabric · error

invalid deployment spec

Error message

invalid deployment spec

What it means

ExtractStatedbArtifactsFromCCPackage derives statedb (CouchDB) index artifacts from the chaincode package's code package via MetadataAsTarEntries. If the metadata extraction fails — typically because the code package is not a valid tar or contains no META-INF/statedb artifacts — this error is returned (the detailed cause is only logged).

Source

Thrown at core/common/ccprovider/cc_statedb_artifacts_provider.go:50

		// we can abort the chaincode instantiate/upgrade/install operation.
		ccproviderLogger.Infof("Error while loading installation package for ccNameVersion=%s Err=%s", ccNameVersion, err)
		return false, nil, nil
	}

	statedbArtifactsTar, err = ExtractStatedbArtifactsFromCCPackage(ccpackage)
	return true, statedbArtifactsTar, err
}

// ExtractStatedbArtifactsFromCCPackage extracts the statedb artifacts from the code package tar and create a statedb artifact tar.
// The state db artifacts are expected to contain state db specific artifacts such as index specification in the case of couchdb.
// This function is called during chaincode instantiate/upgrade (from above), and from install, so that statedb artifacts can be created.
func ExtractStatedbArtifactsFromCCPackage(ccpackage CCPackage) (statedbArtifactsTar []byte, err error) {
	cds := ccpackage.GetDepSpec()

	metaprov, err := MetadataAsTarEntries(cds.CodePackage)
	if err != nil {
		ccproviderLogger.Infof("invalid deployment spec: %s", err)
		return nil, errors.New("invalid deployment spec")
	}
	return metaprov, nil
}

// ExtractFileEntries extract file entries from the given `tarBytes`. A file entry is included in the
// returned results only if it is located in a directory under the indicated databaseType directory
// Example for chaincode indexes:
// "META-INF/statedb/couchdb/indexes/indexColorSortName.json"
// Example for collection scoped indexes:
// "META-INF/statedb/couchdb/collections/collectionMarbles/indexes/indexCollMarbles.json"
// An empty string will have the effect of returning all statedb metadata.  This is useful in validating an
// archive in the future with multiple database types
func ExtractFileEntries(tarBytes []byte, databaseType string) (map[string][]*TarFileEntry, error) {
	indexArtifacts := map[string][]*TarFileEntry{}
	tarReader := tar.NewReader(bytes.NewReader(tarBytes))
	for {
		hdr, err := tarReader.Next()
		if err == io.EOF {

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Repackage and reinstall the chaincode ensuring the code package is a valid tar.gz containing META-INF/statedb/couchdb/indexes/*.json for CouchDB indexes
2. Check the ccproviderLogger output ('invalid deployment spec: %s') for the underlying tar-extraction cause and fix that first
3. Verify the chaincode source directory layout: indexes must live under META-INF/statedb/couchdb/indexes relative to the chaincode root
4. Confirm the CCPackage passed in was loaded successfully (GetDepSpec non-nil, CodePackage non-empty) before extracting artifacts

Example fix

// before
artifacts, err := ccprovider.ExtractStatedbArtifactsFromCCPackage(ccpack) // ccpack.CodePackage empty
// after
if ccpack.GetDepSpec() == nil || len(ccpack.GetDepSpec().CodePackage) == 0 {
    return errors.New("chaincode package has no code package; reinstall with valid tar.gz source")
}
artifacts, err := ccprovider.ExtractStatedbArtifactsFromCCPackage(ccpack)

depspec := ccpack.GetDepSpec()
if depspec == nil || len(depspec.CodePackage) == 0 {
    return errors.New("no code package; reinstall chaincode with valid tar.gz source")
}
artifacts, err := ccprovider.ExtractStatedbArtifactsFromCCPackage(ccpack)

func hasCodePackage(c ccprovider.CCPackage) bool {
    d := c.GetDepSpec()
    return d != nil && len(d.CodePackage) > 0
}

artifacts, err := ccprovider.ExtractStatedbArtifactsFromCCPackage(ccpack)
if err != nil {
    if err.Error() == "invalid deployment spec" {
        return fmt.Errorf("code package is not a valid tar or has no statedb metadata; see ccprovider log for cause: %w", err)
    }
    return err
}

When it happens

Trigger: Calling ExtractStatedbArtifactsFromCCPackage with a CCPackage whose GetDepSpec() returns a spec with a nil/empty or non-tar CodePackage, e.g. a chaincode installed without the source packed as a tar.gz, or corrupted install package bytes.

Common situations: Chaincode installed with `peer chaincode install` where the input was not a valid archive; index artifacts missing under META-INF/statedb/couchdb/indexes; package corrupted during upload; Go chaincode packaged without -s/--source handling producing empty code package.

Related errors

• error inspecting next tar header
• tar entry %s is not a regular file, type %v
• did not find file '%s' in package
• could not read %s from tar
• illegal file name in payload: %s

AI-assisted analysis of hyperledger/fabric@2736b63f8f (2026-09-04). Data as JSON: /api/errors/8a4044d9667047da. Report an issue: GitHub.