Installation troubleshooting guide

Introduction

Native software can be installed onto a Symbian OS device only if it is present in a SIS file. The Software Installer (SWI) is a component of Symbian OS which analyses the contents of a SIS file and determines whether the contents can be installed or not. This document describes the most common reasons for installation failure.

This information only applies to Symbian OS v9.x onwards. In earlier releases, it was not necessary to use the installer because files could be manually copied onto the device.

Note that the user interface for the Software Installer is provided by the device manufacturer rather than by Symbian. Therefore any error codes or messages displayed during installation are likely to vary from device to device. Each section in this document lists the error codes passed by the Software Installer engine to the UI, which may help in the diagnosis process.

Generic failures

This section describes the most common reasons for installation failure that could apply to any SIS file.

Was the SIS file built using Symbian OS v9.x tools?

KErrLegacySisFile

The format of SIS files changed significantly between Symbian OS v8.x and v9.x.

For example, support was added for signing with multiple certificates, and the storage of additional file metadata such as platform security capabilities.

If an attempt is made to install a pre-v9.x format SIS file onto a device, it will fail.

Note that the structure of executables also changed, so even if v8.x SIS files could be installed, the executables would not run.

The SIS file must be created either with the CreateSIS tool or version 4 or higher of MakeSIS (makesis – v displays the version number).

Are the binaries in the SIS file compatible with the target environment?

KErrWrongHeaderFormat

SWI will not install a SIS file that contains the wrong type of executables for the target environment. For example, ARM executables will not install on the emulator and emulator executables will not install on a phone.

Are the file and path names inside the SIS file correct?

EUiInvalidFileName
KErrSISInvalidTargetFile

Are there any typographical mistakes in the path names or file names specified in the .pkg file?

Are there dependencies which cannot be met?

KErrSISPrerequisitesMissingDependency

Does the SIS file contain software dependencies (specified in the corresponding .pkg file) which cannot currently be met? If the package depends on the presence of some other software components, the Software Installer checks if they are installed on the device and generates an error if not.

Although the SIS file can specify dependencies on software components contained in embedded SIS files, SWI detects this and does not generate an error in such circumstances, but only if the embedded component is selected for install. In other words, a conditionally installed embedded SIS file will not satisfy a dependency in the parent file if the condition fails.

Is the SIS file too deeply embedded?

KErrSISTooDeeplyEmbedded

A level of embedding that exceeds the maximum depth of 8 was found in the SIS file.

Was the SIS file built with a hardware dependency field incompatible with the device?

EQuestionIncompatible

The Software Installer verifies that the SIS file is compatible with the target hardware, as specified in the hardware dependency statement in the corresponding .pkg file. Note that a package can specify multiple hardware dependencies.

Installation may fail if the package is not compatible with the target device, or the device's installer UI may ask the user if they wish to continue with the installation anyway.

The software installation policy setting SISCompatibleIfNoTargetDevices determines whether SIS files without any hardware dependency statements are considered compatible.

Does the SIS file contain a protected Secure ID (SID) or Vendor ID (VID)?

EUiVIDViolation
EUiSIDViolation
KErrSecurityError

In Symbian OS v9.x each .exe has a SID which, unless explicitly specified by the SECUREID keyword in its MMP file, defaults to be the same value as the application's 3rd UID. The SID value is not relevant for DLLs as a process's SID will always be that of its EXE.

A VID can be used as a runtime mechanism to check that a binary comes from a particular source. It is specified by using the VENDORID keyword in a project's MMP file; if this is not found, the VID will default to zero.

UID values are split into a protected range and an unprotected range. If a SIS file contains an executable with a SID or VID from the protected range, or if its package UID is from the protected range then the Software Installer will not install the contents unless the SIS file is trusted; in other words, signed with at least one verifiable end entity (EE) certificate.

See Symbian Signed for more information on allocating UIDs.

Does the file contain an .EXE with a SID which is already in use?

KErrAlreadyExists

Installation fails if the package contains an executable with the same SID as another executable on the device (either in ROM or previously installed) and the package is not a valid upgrade of the original (see Upgrading Rules). This situation can occur if the SID is from the unprotected range.

Is there enough space for the SIS file to be installed?

KErrDiskFull
KErrNoMemory
KErrSISNotEnoughSpaceToInstall
EUiInsufficientSpaceOnDrive

Either the installer may run out of memory or there may not be enough disk space to install the contents.

To resolve this, you may need to free up some space on the target drive.

Is some or all of the SIS file's content already installed?

KErrSISWouldOverWrite
EUiBlockingEclipsingFile
KErrInvalidEclipsing
EUiAlreadyInRom

A package may contain a file that is already present on the device and this may cause the installation to fail. If the file is already present in ROM then the package must conform to eclipsing rules (see Eclipsing rules) in order to install. If the file is present on the device from a previous installation then the package must conform to both eclipsing and overwriting rules in order to install.

The Software Installer allows the overwriting or deleting of a file in the following situations:

if the install package has been identified as a valid upgrade of the original package that installed the file, then it may be able to overwrite and delete files installed by the original package, depending on its package type.
if the software installation policy setting AllowOrphanedOverwrite is set to true, then the user is asked whether to allow the overwriting of orphaned files during the installation. An orphaned file is any file that is not owned by a package, for instance a newly created file.

To avoid the possibility of conflicting files, it is recommended to install private application data files to the application's private directory (/private/SID/). In an automated test environment, the emulator environment may need to be cleaned or reset after each test run. Alternatively; an appropriate test may need to uninstall an installed package before continuing.

If the intention is to upgrade a package, ensure you have used the same package UID and package name as the original, otherwise SWI may treat it as a new package and clashing files may prevent it from installing.

Has the SIS file been tampered with?

KErrBadHash

If a package has been properly signed and the necessary certificates are present on the device then installation will still fail in the unlikely event that the package has been tampered with. A digital signature is invalidated by any change in the signed data, in which case the checksums and digital signatures might no longer match the rest of the data in the package.

Is the SIS file corrupt?

EUiFileCorrupt

A SIS file is corrupt, meaning that the checksums stored in the file do not match the actual checksum. The error may be generated while attempting to read the SIS file. Note that this is not the same as KErrBadHash, which is generated when the digital signatures mismatch.

KErrSISControllerMissingPrerequisites

Is the SISPrerequisites field missing in a SIS controller?

KErrSignatureSchemeNotSupported

The security policy file declared a signature scheme which is not supported by the Symbian OS.

Is the policy file corrupt?

KErrPolicyFileCorrupt

The policy file (z:\system\data\swipolicy.ini) on the device is corrupt. It may be generated if a read error occurs while attempting to read the SIS file. Note that this is not the same as KErrBadHash, which is generated when the digital signatures mismatch.

Have the correct target directories been specified?

KErrSISInvalidTargetFile
KErrGeneral
KErrAccessDenied

Prior to Symbian OS v9.x a package was free to install files anywhere in the file system. v9.x introduced data-caging as part of Platform Security, meaning that restrictions are applied to where files can be installed.

The file system has the following structure:

`/sys/`	This is the restricted system area, accessible only to processes with `TCB` or `AllFiles` capabilities. A package should not attempt to install any files here.
`/sys/bin/`	All executables must be installed to and run from this directory. For example, the .pkg from which the package is generated might contain a line such as the following: `"HelloWorld.exe"-"!:\sys\bin\HelloWorld.exe";`
`/private/`SID`/`	This is the private file system area for the application, where SID is the unique security identifier for the process. Applications use this area to hold their private files such as .ini, .mbm and data files. For example, a .pkg might contain a line such as the following: `"helloworld.ini"-"!:\private\80334568\helloworld.ini";` where `0x80334568` is the SID (by default the 3rd UID) specified in `helloworld.mmp`. A package cannot generally install a file into another program's private directory area. To allow for cases where it is desirable to do this, a package can install files in or below directories named `import` in another program's private directory (i.e. `\private\`SID`\import\`). Note that installation into an import directory is only possible if it pre-exists.
`/resource/`	The location for application icons, bitmaps etc. Writing is allowed only at application installation. Everyone can read the contents of the folder. For example, a .pkg might contain a line such as the following: `"helloworld.rsc"-"!:\resource\apps\helloworld.rsc"`

Other directories not mentioned above are public, and can be read from and written to by any program.

Some possible causes of installation failure are:

attempting to place a non executable into /sys/bin will generate KErrSISInvalidTargetFile,
attempting to place an executable into /sys/ will generate KErrAccessDenied,
attempting to place a file in /private/ will generate KErrGeneral,
attempting to place a file in /private/0x80334568 where 0x80334568 is the UID/SID of the application being installed will generate KErrAccessDenied. The location should be /private/80334568.

Is information missing from the SIS file?

KErrSISFieldIdMissing

The FieldId was not found during SIS file parsing.

KErrSISInfoSISNamesMissing

The SISNames field was not found in a SISInfo structure. This might happen if a name was not found for a specific language. This means that the number of languages specified is higher than the number of language names specified in a SISInfo structure.

KErrSISInfoSISVendorNamesMissing

The SISVendorNames field was not found in a SISInfo structure. This might happen if a vendor name was not found for a specific language. This means that the number of languages specified is higher than the number of vendor names specified in a SISInfo structure.

KErrSISFileOptionsMissing

The SISFileOptions field was missing.

Signing/certification failures

The SIS file must be signed correctly. You can use CreateSIS (a wrapper around MakeSIS and SignSIS) to automate the process of generating and signing SIS files. Alternatively, you can use SignSIS to sign SIS files after using MakeSIS to generate them. You cannot use MakeSIS to do signing.

SIS file signing states

A SIS file may either be:

Unsigned, in which case it cannot be installed at all onto a device which has been configured by the manufacturer to disallow the installation of unsigned packages.
Signed by a signing authority, for instance Symbian Signed. In this case the certificate that it is signed with is derived from the Symbian B root certificate which is present on most devices. The Symbian B certificate is a CA certificate, created by VeriSign Inc.
Signed with an ACS Publisher ID certificate. In this case it will not chain to a root certificate on the device.
Signed with some other certificate, for example one that has been generated using the makekeys tool. In this case it will not chain to a root certificate on the device.
Signed with a Symbian Signed Developer Certificate, which allows installation to proceed but only subject to certain constraints, for instance that it must be installed on a device with a specific IMEI or is only valid for installation for a certain time period.
Signed with a certificate which chains back to a trusted anchor other than the Symbian B root certificate, for instance signed with a licensee's certificate.

Note that a SIS file can be signed with more than one certificate.

The term self signing is used when the SIS file is signed by the creator of the SIS file. This will be the case if it is signed using either:

a certificate that has been self generated (by makekeys.exe for example),
a counter-signed certificate such as ACS Publisher IDs.

Self-signed SIS files are not associated with a root certificate which is present on the device. A Developer Certificate is indirectly signed against one of the Symbian root certificates which are present on the device by default.

For more details on Symbian Signed, the signing process, ACS Publisher ID certificates and Developer Certificates see www.symbiansigned.com.

Does the certificate exist?

ENoCertificate

A certificate for the SIS file cannot be found.

Does the SIS file need to be signed?

ESignatureNotPresent

The device may require that all SIS files be signed before they can be installed. This will be the case if the AllowUnsigned setting in the SWI policy file is set to false. Note however that if AllowUnsigned is set to true then an unsigned SIS file can only be installed if no executables within it have any system capabilities.

Note that if a SIS file is signed, its signature does not propagate to any SIS files embedded within it, so embedded SIS files will also require signing.

If the SIS file is self signed but the installation still fails, then there may be a mandatory root certificate on the device, in which case the SIS file must be signed with a certificate which chains to that mandatory root certificate (or to multiple mandatory root certificates).

Is the certificate self-signed or is its status unknown?

ESignatureSelfSigned

The signature on the SIS file validates correctly but chains back to a self-signed root.

Is there a mandatory root certificate on the device?

EMandatorySignatureMissing

If there is a root certificate in the device's Software Installer certificate store (swicertstore) which is marked as MANDATORY, all SIS files must be signed with a verifiable end entity (EE) certificate which chains to that root certificate (and to any other root certificates also marked as MANDATORY on the device). This means that unsigned and self-signed packages will not be installable, even if the software installation policy setting AllowUnsigned is set to true.

In general, embedded SIS files are treated as separate files from the SIS file they are embedded in. They do not inherit signatures or capabilities from their owner. The only exception is if a MANDATORY root certificate is present in the device's SWI certificate store. In this case, only the outer (embedding) SIS file needs to be signed with a verifiable EE certificate chaining to that root certificate. The inner (embedded) SIS files do not. This allows the SIS file's creator to embed the packages they need without having to get them all individually signed to the MANDATORY root.

Note that installation may still fail, even if the SIS file is signed with a verifiable EE certificate which chains back to a mandatory root certificate, if the SIS file contains executables with Platform Security capabilities which themselves require signing with a certificate that endorses those capabilities.

Has the certificate expired?

ECertificateValidationError
KErrSecurityError

A root certificate might exist on the device but it might be invalid due to the current date being outside the validity period for the certificate. A likely cause is if the PC clock, (on which CreateSIS is run) is ahead of the device clock (on which the installation is run) by a time interval greater than the time taken to copy the SIS file to the device and start the installation. It should be ensured that the phone is set to the current date and that the certificate’s expiry date has not passed.

The createsis dump command can be used to show the validity period for the certificate used to sign the SIS file.

Are the certificate store and root certificate present?

KErrNotFound

The store containing the root certificates (known as the swicertstore) may not be present on the device or may be empty.

The ROM swicertstore should be present at z:\resource\swicertstore.dat (or \Epoc32\release\platform\target\z\resources\swicertstore.dat on the emulator).

Note: if the installation is being made onto a production device then this problem is highly unlikely to occur, but is more likely to occur if the installation is being performed using the emulator or onto a test device (where the ROM has been re-flashed, for example).

Is the SIS file signed with a Developer Certificate?

If a SIS file signed with a Developer Certificate does not install, then it is possible that you are using the certificate outside of the context agreed with the DevCert issuer. The following points should be checked:

The SIS file may have been signed with the wrong Developer Certificate, or signed multiple times with different Developer Certificates.
Developer Certificates are issued for a particular device or devices. If an attempt is made to install to any other device, installation will fail.
The Developer Certificate may have expired.
The Developer Certificate may not endorse the full set of capabilities that the SIS file contents require.
The SIS file is being installed onto a test device and the Symbian A root certificate is not present on the device.
An OCSP check fails. An OCSP check is not required for Developer Certificates, so this check should be disabled if possible (for example, via the control panel).

Does the SIS file need to be signed with a certificate with a code signing extension?

ECertificateValidationError
ENoCodeSigningExtension

If the MandateCodeSigningExtension policy setting in the SWI policy file is set to true, the verifiable end entity (EE) certificate used to sign the SIS file must have the code signing extension OID 1.3.6.1.5.5.7.3.3.

This is only expected to be encountered by device manufacturers or signing authorities during device testing. See RFC 3280 for further details.

Does the SIS file need to be signed with an OID specified on the device?

ECertificateValidationError
ENoSupportedPolicyExtension

If the MandatePolicies policy setting in the SWI policy file is set to true then all non root certificates in chains corresponding to the private keys used to sign the SIS file must contain at least one OID specified in the policy file.

This is only expected to be encountered by device manufacturers or signing authorities during device testing. See RFC 3280 for further details.

Is an unsupported signature scheme used?

KErrSignatureSchemeNotSupported

The security policy file declared a signature scheme which is not supported by the Symbian OS.

Is an unsupported digest function used?

KErrDigestNotSupported

An unsupported digest function was used in a signed SIS file.

Certificate revocation failures

This section describes reasons for installation failure related to certificates that have been revoked. Symbian uses OCSP (Online Certificate Status Protocol) to achieve this.

Has the certificate been revoked?

ECertificateStatusIsRevoked

If the OcspEnabled policy setting is set to true, the software installer will perform an OCSP check during software installation and if a revoked response is received, installation will fail.

Note that if the OcspMandatory policy setting is set to true and there is a lack of a positive response when the OCSP check is performed (for instance because the OCSP server is unreachable), the installation will fail and return an ECertificateStatusIsUnknown error as described below.

Is the OCSP check unable to return a definite answer?

ECertificateStatusIsUnknown

The OCSP revocation check could not return a definite answer on this certificate. The error is not critical and the user should get a choice as to whether to cancel the installation after the warning is displayed.

EInvalidCertificateStatusInformation

The OCSP revocation check returned a malformed reply, and the revocation check on the certificate could not be performed.

ECertificateSelfSigned

The OCSP revocation check could not return an answer on this certificate, because it is self-signed and cannot be revoked through standard mechanisms. This error can be returned only if OCSP is enabled. The error is not critical and the user should get a choice as to whether to cancel the installation after the warning is displayed.

Capability related installation failures

This section describes the reasons for installation failure relating to SIS files requiring Platform Security capabilities.

In Symbian OS v9, a series of Platform Security measures were implemented throughout the system, one of which is known as the capability model.

A capability grants access to APIs and files. The Platform Security architecture defines a number of capabilities, such as access to the phone stack or to the complete file system. To access certain resources, a client program must hold the appropriate capability. Capabilities are listed in the program's .MMP file. The complete set of capabilities is enumerated in the TCapability enum (e32capability.h). They are divided into two groups; system and user. The software installer behaves differently depending upon whether the software being installed requires no capabilities, only user capabilities, or system capabilities.

The capabilities an executable needs can be determined by referring to the Symbian OS library documentation. If third party binaries are being linked to then the petran tool (which is supplied on SDKs) can be used to get information about the capabilities of ARM executables, for example:

petran –dump s somedll.dll

The table below lists Symbian's recommended set of user capabilities, but note that the phone manufacturer or network operator may define a different set, using the UserCapabilities section of the SWI policy file.

`NetworkServices`	Grants access to remote services without any restriction on its physical location i.e. grants access to the phone network. An application that has been given this capability can dial a number, send a text message etc. and thus may incur a cost for the phone user.
`LocalServices`	Grants access to remote services in the close vicinity of the phone i.e. grants access to the local network. An application with this capability can send or receive information through Bluetooth, USB or IR. In most cases such services will not incur a cost for the phone user.
`UserEnvironment`	Grants access to live confidential information about the user and his/her immediate environment. Examples are biometric data (such as blood pressure), audio and video recording.
`ReadUserData`	Grants read access to user data, for example contacts, messaging and calendar data.
`WriteUserData`	Grants write access to user data.
`Location`	Grants access to the live location of the device. This capability supports the management of the user’s privacy regarding the phone location. Location information protected by this capability can include map co-ordinates and street address, but not regional or national scale information.

Does the SIS file's content require user capabilities?

EUiCapabilitiesCannotBeGranted
KErrSecurityError

If the contents of the SIS file being installed have no capabilities then it is considered for installation without any capability related checking.

If an executable within a SIS file has user capabilities but is not signed with a certificate endorsing those capabilities, then installation may fail:

If the AllowGrantUserCapability policy setting in the SWI policy file is set to true then at installation time the user will be asked if they wish to grant the capabilities to the executables being installed. If the user fails to grant one or more of the required capabilities then the installation will fail.
If AllowGrantUserCapability is set to false then the device is not configured to allow users to grant the capabilities and the package must be signed with a certificate which chains to a root certificate on the device that endorses the requested capabilities.

Does the SIS file's content require system capabilities?

EUiCapabilitiesCannotBeGranted
KErrSecurityError

If an executable within a package has any system capabilities, they must be endorsed by an appropriate certificate otherwise installation will fail. This means that the SIS file must be signed with a verifiable end entity (EE) certificate(s) which chains to a root certificate(s) on the device which endorses the necessary system capabilities.

If the SIS file does not require any system capabilities, it may not be necessary to sign the package. Any user capabilities that are required and not signed-for will be presented to the user for final authorisation.

Is there a mismatch of capabilities?

KErrCapabilitiesMismatch

There is a mismatch between the capabilities declared in the executable and those found in the SIS file controller section. This may occur if the capabilities declared in the .pkg file used for building the SIS file do not match the union of capabilities of the executables inside it. You should check the CAPABILITY declaration in the SIS package definition.

Package type installation failures

This section describes some reasons for installation failure which relate to the specific type of SIS file used.

There are five types of SIS file installation packages (SA, SP, PU, PA, and PP), each of which has a set of rules which must be adhered to in order for installation to be successful. See here for a description of the different package types. Some specific problems which result in installation failure are as follows.

Does an augmentation package have the same name as the base package?

KErrAlreadyExists

An attempt was made to install an augmentation package (of type SP) with the same package name as the base package. Augmentation packages should have a different name from the base package.

Is an augmentation package unsigned but the base package signed?

KErrSecurityError

An attempt was made to install an unsigned augmentation package (of type SP), but the base package was signed. SP packages should be signed if the base package was signed.

Is an augmentation package delivering a file which is already installed?

KErrSISWouldOverWrite

An attempt was made to install an augmentation package (of type SP) to a drive where the corresponding base package is already installed and the augmentation package contains a file which was previously installed by the base package. Augmentation packages can only add files to a base package; they cannot overwrite existing files.

Is a SIS file attempting to eclipse a ROM file and no SIS controller file exists?

EUiAlreadyInRom
KErrInvalidEclipsing

If a standard package (type SA) attempts to install an application which is already in ROM and for which a SIS controller file does not also exist in ROM. ROM code is not upgradeable if there isn’t an associated SIS stub controller file also present in ROM.

Is the base package missing from the device?

EUiMissingBasePackage
KErrMissingBasePackage

An installation of an augmentation (type SP), partial upgrade (type PU) or pre-installed patch (type PP) failed because the base package is not present on the device.

Is the package valid?

KErrInvalidUpgrade

An upgrade failed because the package being installed is not a valid upgrade of the package on the device. For more information on upgrading, see How to upgrade OS components and Upgrading rules.

Expression evaluation failures

This section describes failures because of expression errors.

Is there a problem with the expression?

KErrInvalidExpression

An invalid expression format has been encountered.

KErrExpressionToComplex

A boolean expression in the SIS file is too complex. The SIS file needs to be rebuilt with fewer logical conditions.

Are the type and operator valid?

KErrInvalidType

An invalid type has been found while evaluating an expression.

KErrSISUnexpectedFieldType

An unexpected field type was found while parsing a SIS file. This is most likely to happen when a certain field type is expected in a certain structure, and another one is detected instead.

KErrSISExpressionUnknownOperator

An unknown operator was encountered in a SISExpression.

Is the string length valid?

KErrSISInvalidStringLength
KErrSISStringInvalidLength

These are specific cases of KErrSISFieldLengthInvalid for SISString. In addition to the cases documented for KErrSISFieldLengthMissing, these errors can occur whenever a string with an invalid length is specified.

Compression failures

This section describes failures due to compression.

KErrSISCompressionNotSupported

An unknown compression algorithm was encountered in a SIS file.

Index of installation failure codes

EUiAlreadyInRom (Is some or all of the SIS file's content already installed?)

EUiAlreadyInRom (Is a SIS file attempting to eclipse a ROM file and no SIS controller file exists?)

EUiFileCorrupt

EUiDiskNotPresent – An attempt is being made to access a removable media drive (i.e. to read a SIS file from it) but the drive is not present or not ready to be accessed.

EUiCannotDelete – An attempt is being made to delete a file but it is in use.

EUiInvalidFileName

EUiInsufficientSpaceOnDrive

EUiCapabilitiesCannotBeGranted (Does the SIS file's content require user capabilities?)

EUiCapabilitiesCannotBeGranted (Does the SIS file's content require system capabilities?)

EUiMissingBasePackage

EUiConstraintsExceeded – Constraints imposed by a developer mode certificate have been exceeded.

EUiSIDViolation

EUiVIDViolation

EUiUIDPackageViolation

EUiSIDMismatch – An attempt is being made to install a file to a private directory where the SID in the SIS file does not match the SID of the target directory (i.e. /private/<SID>).

EUiBlockingEclipsingFile

ESignatureSelfSigned

ENoCertificate

ESignatureNotPresent

ESignatureCouldNotBeValidated – An error occurred while the SIS file signature was being validated.

ECertificateValidationError (Has the certificate expired?)

ECertificateValidationError (Does the SIS file need to be signed with a certificate with a code signing extension?)

ECertificateValidationError (Does the SIS file need to be signed with an OID specified on the device?)

ENoCodeSigningExtension

ENoSupportedPolicyExtension

EMandatorySignatureMissing

EQuestionIncompatible